diff --git a/operations/functionality-gap-audit-2026-07-25.md b/operations/functionality-gap-audit-2026-07-25.md new file mode 100644 index 0000000..7bc2fb1 --- /dev/null +++ b/operations/functionality-gap-audit-2026-07-25.md @@ -0,0 +1,267 @@ +# DRE Functionality Gap Audit + +**Date:** July 25, 2026 +**Purpose:** Identify what's needed to go from static HTML portal to a functional end-to-end debt recovery system +**Audience:** Germaine Brown, Tony Brown, Anita Brown + +--- + +## Executive Summary + +The DRE project has a **mature specification** (detailed fee structures, tiered recovery workflow, 8 letter templates, compliance framework, AI analysis design) and a **polished static HTML portal** (12 pages across public/internal, dark theme, consistent nav, Agent DRE chatbot widget). However, there is **zero backend infrastructure** connecting the portal to any real data or services. Every page uses static mock data. No claim submission works end-to-end. No payment can be collected. No letter can be sent. + +The gap from "looks like a business" to "is a business" is roughly **3-6 months of focused backend engineering**, depending on scope. + +--- + +## Part 1: Current State — What Actually Exists + +### ✅ Working Infrastructure + +| Component | Status | Details | +|-----------|--------|---------| +| **TwentyCRM** | Running | PostgreSQL + Redis + NestJS at `crm.debtrecoveryexperts.com`. Custom objects created: Debtors, Claims, CaseNotes, Payments. Claim→Debtor relation exists. Basic schema populated. | +| **DocuSeal** | Running | Deployed at `sign.itpropartner.com`. API token exists (info@itpropartner.com). | +| **IMAP Email Poller** | Running | Python script polls dre@ and collections@ every 60s via Hermes cron. Writes to `/var/www/internal/data/dre-mails.json`. | +| **DRE MCP Server** | Running | FastMCP server on localhost:8900. 3 tools: get inbox, get pending letters, update letter status. Reads/writes static JSON. | +| **Inbox Page** | Working | `/var/www/internal/inbox.html` fetches from dre-mails.json via JS. | +| **Caddy Reverse Proxy** | Working | portal.debtrecoveryexperts.com serves public pages, crm.debtrecoveryexperts.com proxies to TwentyCRM. | +| **Scraping Stack** | Configured | Firecrawl, ScrapingAnt, SearXNG all have API keys and are tested. | +| **Compliance Docs** | Drafted | 3 documents (ToS, Privacy Policy, Compliance Manual v1.1 — 23 sections). Mechanics lien research. Credit reporting analysis. **All marked DRAFT — attorney review required.** | +| **Letter Templates** | Documented | 8 templates: 3 auto (onboarding, under review, LPOA enclosed), 5 queued (soft touch, formal demand, lien threat, escalation, legal action). | + +### ✅ Portal Pages Deployed + +**Public (`/var/www/capabilities/`):** +- `debt-recovery.html` — intake form with Agent DRE chatbot, real file upload, elevator-pitch responses +- `login.html` — SSO-only gateway pointing to Cloudflare Access +- `dre-fee-calculator.html` — 4-tier fee projection widget +- `dre-pay.html` — static debtor payment landing page + +**Internal (`/var/www/internal/`):** +- `index.html` — landing page with 4 navigation cards +- `dre-dashboard.html` — claims dashboard (102 lines, mock data) +- `dre-case-aging.html` — stalled case monitor (158 lines, mock data) +- `dre-client-dashboard.html` — client view preview (mock data) +- `letter-queue.html` — demand letter composer with AI sidebar, approval workflow, Anita notification (1321 lines, full-featured mockup) +- `dre-analytics.html` — AI score distribution, recovery by tier, monthly trends (304 lines, mock data) +- `inbox.html` — unified inbox from JSON endpoint (357 lines, connected to real data) + +--- + +## Part 2: What's Missing — The Backend Gap + +### Critical: No Backend API Server + +**The single biggest gap.** There is NO backend service that the portal pages can call. Every page uses hardcoded mock data. No claim submission pipeline exists — the intake form's submit button goes nowhere. No case management API. No payment processing endpoint. + +**What's needed:** +- A Python (FastAPI) or Node.js API server +- REST endpoints for: claim submission, claim status, case notes, payments, debtor lookup +- Database: either build on top of TwentyCRM's GraphQL/REST APIs, or deploy a separate PostgreSQL database +- Authentication: JWT or session-based auth for clients and DRE staff + +### Missing Integrations (All of Them) + +| Service | Spec Requirement | Current State | Gap | +|---------|-----------------|---------------|-----| +| **Stripe Connect** | ACH payments, 0.8% cap $5 | No keys in .env | Must register for Stripe Connect, get API keys, build payment flow | +| **DocuSeal API** | Automated signing envelopes for LPOA, ToS | DocuSeal deployed but NOT integrated into portal | Build API calls from portal to DocuSeal for automated signing requests | +| **LetterStream** | Certified mail, ~$8.34/letter | API credentials exist (rzv56x1v / 5ezy56k2ny7a8vx14u). Account needs Automation mode activation. | Must activate account, then build API integration | +| **Online Notary (OneNotary/Proof)** | RON for LPOA, ~$25/session | No account, no API keys | Must create account, integrate API | +| **Cloudflare Turnstile** | Bot protection on intake form | Not implemented on debt-recovery.html | Add Turnstile widget | +| **Partner Law Firm** | Litigation referral, 25% fee split | No agreement in place | Business relationship needed | + +### Missing Automation Workflows + +| Workflow | Spec Says | Current State | +|----------|-----------|---------------| +| **Claim submission pipeline** | Client submits → AI scores → team reviews → accept/reject → LPOA → recovery | Submit button is decorative | +| **AI Claim Analysis** | Claude Opus scores 0-100, weakness analysis, debtor research | Not built. Scraping keys exist but no scoring pipeline | +| **Automated letter sending** | Templates 1-3 auto-send on trigger events | Templates exist as text docs. No sending code | +| **Demand letter approval flow** | Anita drafts → Tony/Germaine approve → send via collections@ | Letter-queue.html has the UI but no backend to persist or send | +| **LPOA generation & notarization** | DocuSeal envelope → sign → notarize via RON | Neither automated | +| **Tier progression** | Day 1-5: Tier 1, Day 7-14: Tier 2, etc. | No cron jobs or timers to advance tiers | +| **Case binder generation** | Two PDFs + ZIP on close | Not built | +| **Payment disbursement** | Receive funds → deduct fee → disburse to client | No payment processing at all | +| **Notification system** | Hourly approval reminders to Germaine + Tony | Script exists but reads from non-existent file | +| **Audit trail** | Every edit tracked: who, what (old→new), when, why | Not implemented | + +### Infrastructure Gaps + +| Issue | Impact | +|-------|--------| +| **No `internal.debtrecoveryexperts.com` in Caddy** | Internal pages are not accessible — DNS resolves but no Caddy route exists. The entire internal dashboard (Claims, Aging, Letters, Inbox, Analytics) cannot be reached by the team. | +| **TwentyCRM relations incomplete** | Payment→Claim and CaseNote→Claim relations are missing. These are needed for associating payments and notes to claims. | +| **DRE MCP server too minimal** | Only reads static JSON files. No CRUD operations. No integration with TwentyCRM. | +| **No `pay.debtrecoveryexperts.com` resolution** | DNS resolves but no Caddy route. Debtor payment URL in all letter templates points to a non-existent service. | + +### Legal/Compliance Prerequisites for Operations + +| Requirement | Status | +|-------------|--------| +| **Texas Debt Collector Bond/Registration** | NOT DONE — Texas Finance Code Ch. 392 requires third-party collectors to be bonded/registered. This is a legal prerequisite before collecting any debt. | +| **Attorney Review of All Drafts** | NOT DONE — ToS, Privacy Policy, Compliance Manual all marked DRAFT. Must be reviewed by a Texas-licensed attorney. | +| **FDCPA Compliance Implementation** | NOT DONE — Validation notice, Mini-Miranda, cease communication protocols must be built into the system, not just documented. | +| **LPOA Template Finalization** | NOT DONE — Must be legally reviewed. Current docs mention it but no final template exists. | + +--- + +## Part 3: Minimum to Go Live with ONE Real Claim + +If Germaine and Tony need to accept ONE claim, send ONE demand letter, and collect ONE payment (even manually), here's the absolute minimum: + +### Phase 0 — Legal (Do First — 2-4 weeks) +1. **Attorney review** of ToS, Privacy Policy, Compliance Manual, LPOA template +2. **Register with Texas** — bond/registration as debt collector under TX Finance Code Ch. 392 +3. **Open business bank account** for trust/escrow of collected funds (required by FDCPA) + +### Phase 1 — Manual MVP (2-4 weeks) +1. **Build basic API server** with: + - POST `/api/claims` — accepts intake form submission, writes to TwentyCRM or SQLite + - GET `/api/claims/:id` — returns claim status + - Basic auth (API keys or simple JWT) +2. **Wire intake form submit** — `debt-recovery.html` form → POST to API +3. **Build claim dashboard backend** — replace mock data in `dre-dashboard.html` with real API calls +4. **Stripe payment link** — create a manual Stripe payment link for the debtor (no integration needed, just a hosted page) +5. **Send first demand letter manually** — use LetterStream web UI or print/mail + +### Phase 2 — Semi-Automated (2-4 weeks) +1. **Stripe Connect integration** — full API integration for automated payment collection +2. **LetterStream API integration** — automated certified mail from portal +3. **DocuSeal API integration** — automated LPOA signing requests +4. **Email automation** — auto-send templates 1-3 on trigger events + +--- + +## Part 4: Prioritized Punch List + +### 🔴 TIER 1 — BLOCKERS (Can't go live without these) + +| # | Task | Rationale | Effort | +|---|------|-----------|--------| +| 1 | **Attorney review of all legal documents** | ToS, Privacy, Compliance Manual, LPOA are all drafts. Operating without reviewed documents = regulatory risk. Texas bond/registration also falls here. | 2-4 weeks (external) | +| 2 | **Build API backend server** | Every portal page uses mock data. Zero data flows. Must build at minimum: claim CRUD, auth, client/debtor management. Recommend FastAPI (Python) reading/writing to TwentyCRM via GraphQL REST or a standalone SQLite/Postgres. | 2-3 weeks | +| 3 | **Wire portal to API** | Intake form, claims dashboard, client dashboard all need real data. Replace mock data with API calls. | 1-2 weeks | +| 4 | **Fix internal.debtrecoveryexperts.com** | Add Caddy route pointing to `/var/www/internal/`. Without this, the entire internal dashboard is inaccessible to the team. Also set up Cloudflare Access for email-based auth. | 2 hours | +| 5 | **Stripe Connect account + integration** | Can't collect a single dollar without this. Register for Stripe Connect, get API keys, build payment flow (payment link → webhook → mark claim as paid). | 1-2 weeks | + +### 🟠 TIER 2 — OPERATIONAL (Must-have for daily operations) + +| # | Task | Rationale | Effort | +|---|------|-----------|--------| +| 6 | **Automated email sending (templates 1-3)** | Client onboarding emails (received, under review, LPOA enclosed) should fire automatically on claim state changes. Use germainebrown.com SMTP relay. | 3-5 days | +| 7 | **DocuSeal API integration** | Automate LPOA signature requests. Send signing envelope → track status → notify team. | 1 week | +| 8 | **Demand letter approval pipeline** | letter-queue.html has the full UI but needs: (a) letter persistence in DB, (b) approval workflow backend (Anita→Tony/Germaine), (c) actual email sending via collections@ | 1-2 weeks | +| 9 | **LetterStream activation + integration** | Email support@letterstream.com to activate Automation mode on the account. Then build API integration for certified mail with tracking. | 1-2 weeks (after activation) | +| 10 | **Online notary account + integration** | Sign up for OneNotary or Proof. Integrate RON sessions for LPOA notarization. | 1-2 weeks | + +### 🟡 TIER 3 — AUTOMATION (Efficiency multipliers) + +| # | Task | Rationale | Effort | +|---|------|-----------|--------| +| 11 | **AI Claim Analysis pipeline** | Claude Opus scoring (0-100), weakness analysis, debtor research via ScrapingAnt/SearXNG. This is the DRE differentiator — "AI-powered recovery." | 2-3 weeks | +| 12 | **Tier progression automation** | Cron jobs that advance claims through tiers based on time elapsed. Tier 1→2 at day 7, 2→3 at day 21, etc. Triggers new letter generation. | 1 week | +| 13 | **Payment disbursement logic** | When Stripe webhook fires (payment received), calculate fee based on current tier, deduct costs, mark balance for client disbursement. | 3-5 days | +| 14 | **Case binder generation** | Auto-generate DRE Internal PDF, Client Package PDF, Evidence ZIP on case close. Use Python (reportlab/fpdf) to assemble from DB data. | 1-2 weeks | +| 15 | **Audit trail implementation** | Every edit to a claim tracked: field changed (old→new), who, when, why. Add `claim_audit_log` table, wrap all claim mutations. | 3-5 days | +| 16 | **Approval reminder system** | Fix `dre-approval-reminder.sh` to read from real DB. Send notifications to Germaine + Tony via Hermes every 60 minutes when approvals are pending. | 2-3 days | +| 17 | **Fix TwentyCRM relations** | Add Payment→Claim and CaseNote→Claim relations via GraphQL mutation. | 1 hour | + +### 🟢 TIER 4 — POLISH (Post-launch) + +| # | Task | Effort | +|---|------|--------| +| 18 | Client portal with real auth (JWT or Cloudflare Access + tokens) | 1-2 weeks | +| 19 | Cloudflare Turnstile on intake form | 2 hours | +| 20 | Full-text search across claims (Elasticsearch or PG full-text) | 3-5 days | +| 21 | Client-facing case binder download | 2-3 days | +| 22 | Recurring debtor reporting (D&B Global Trade Exchange for B2B, consumer CRAs for personal guarantees) | 1-2 weeks | +| 23 | Analytics dashboard with real data (currently all mock) | 3-5 days | +| 24 | Mobile-responsive polish for all pages | 2-3 days | + +--- + +## Part 5: What's Missing from the Spec That Real Operations Would Need + +### 1. **Client onboarding contract (beyond LPOA)** +The spec assumes clients sign ToS via DocuSeal and LPOA via RON, but doesn't address the full client engagement agreement: scope of services, fee schedule acceptance, dispute resolution, termination rights. This is separate from ToS — it's the per-client engagement letter. + +### 2. **Trust/escrow account management** +FDCPA and state law require collected funds to be held in a trust account separate from operating funds. The spec mentions "disbursement" but nothing about trust account structure, reconciliation, or reporting requirements. + +### 3. **Debtor dispute handling workflow** +FDCPA requires specific procedures when a debtor disputes a debt: cease collection, verify debt, respond within 30 days. The spec mentions this in the compliance manual but has no system workflow for it. Without this, a single disputed claim handled incorrectly = FDCPA violation. + +### 4. **Client communication preferences and consent** +TCPA requires prior express consent for autodialed calls. The spec mentions manual dialing only, but there's no consent capture in the intake form, no opt-out mechanism, and no do-not-contact tracking. + +### 5. **Reporting and metrics for clients** +The client dashboard spec shows tier progress but no actual reporting: recovery rate trends, average time-to-payment, fee transparency breakdown. Clients running a business need real numbers, not just "Tier 2 in progress." + +### 6. **Internal conflict checking** +What happens when two clients submit claims against the same debtor? There's no conflict-of-interest detection or policy. This is a real operational risk. + +### 7. **Staff workload management** +With only 3 people (Germaine, Tony, Anita), there's no capacity tracking, no claim assignment, no SLA monitoring. As volume grows beyond 5-10 claims, this becomes critical. + +### 8. **Payment plan negotiation tracking** +Not every debtor pays in full. The spec assumes binary outcomes (paid/unpaid) but real collections involve payment plans, partial settlements, and structured agreements. No workflow for this. + +### 9. **Document versioning for uploaded evidence** +Clients upload documents. Later they upload revised versions. The system needs to track versions, not just overwrite. Legal discovery requires original + all revisions. + +### 10. **Export/data portability for clients** +When a client leaves DRE, they need their data: all uploaded documents, claim history, communications log. The case binder covers closed claims but not the full portfolio. + +--- + +## Part 6: Technical Architecture Recommendation + +Given the existing infrastructure (TwentyCRM with GraphQL + REST, Python MCP server, IMAP poller), the recommended architecture: + +``` +┌─────────────────────────────────────────────────────────┐ +│ Caddy Reverse Proxy │ +│ portal.debtrecoveryexperts.com → /var/www/capabilities/ │ +│ internal.debtrecoveryexperts.com → /var/www/internal/ │ +│ crm.debtrecoveryexperts.com → localhost:3003 (Twenty) │ +│ pay.debtrecoveryexperts.com → localhost:8001 (FastAPI) │ +│ api.debtrecoveryexperts.com → localhost:8000 (FastAPI) │ +└─────────────────────────────────────────────────────────┘ + │ + ┌───────┴───────┐ + │ DRE API │ + │ (FastAPI) │ + │ Port 8000 │ + │ │ + │ /api/claims │ + │ /api/clients │ + │ /api/letters │ + │ /api/ai │ + │ /api/pay │ + └───────┬───────┘ + │ + ┌───────────────────┼───────────────────┐ + │ │ │ + ┌─────┴─────┐ ┌──────┴──────┐ ┌──────┴──────┐ + │ TwentyCRM │ │ Stripe │ │ DocuSeal │ + │ (GraphQL) │ │ Connect │ │ API │ + │ Port 3003 │ │ │ │ Port 8090 │ + └───────────┘ └─────────────┘ └─────────────┘ +``` + +**Key decisions:** +1. Build a **FastAPI backend** (not Node) — aligns with existing Python skills, IMAP poller, and MCP server +2. **Use TwentyCRM as the database** via its GraphQL API — avoids managing a separate DB schema. TwentyCRM already has Debtors, Claims, CaseNotes, Payments objects. The FastAPI layer wraps TwentyCRM's GraphQL and adds business logic +3. **DRE MCP server** expanded to intermediate between Hermes/Tony and the FastAPI — so Tony can manage claims via Hermes directly +4. **Stripe webhooks** → FastAPI → updates TwentyCRM claim status +5. **Cron jobs** for tier progression, email polling, approval reminders + +--- + +## Summary + +The DRE project has an excellent specification and a polished frontend. The gap is entirely in the **backend** — there's no API, no database integration, no payment processing, no email automation, and no workflow automation. The portal is a beautiful brochure, not yet a functioning business system. + +**If you had to pick the single most impactful next step:** Build the FastAPI backend with `/api/claims` CRUD, wire it to the intake form and dashboard, and integrate Stripe for payments. That alone bridges the "looks like a business" to "collects money" gap.