# Debt Recovery Platform Architecture

The Debt Recovery Experts (DRE) platform at debtrecoveryexperts.com. Contractors/owner-operators submit unpaid debt claims, DRE reviews, collects, and disburses minus a fee.

## Tech Stack (planned)

| Component | Technology | Status |
|-----------|-----------|--------|
| Marketing site | WordPress (existing) | Live |
| Customer portal | Custom at portal.debtrecoveryexperts.com | Mockup done |
| Internal dashboard | Dark-themed (app.itpropartner.com/dre-dashboard.html) | Mockup done |
| Client dashboard | Light-themed (app.itpropartner.com/dre-client-dashboard.html) | Mockup done |
| Claim intake form | Split-screen ScrapingAnt-inspired (debt-recovery.html) | Mockup done |
| Case aging | (app.itpropartner.com/dre-case-aging.html) | Mockup done |
| Debtor payment page | Minimal single-card (app.itpropartner.com/dre-pay.html) | Mockup done |
| Fee calculator | Live calculation by tier (dre-fee-calculator.html) | Mockup done |
| Signing | DocuSeal (sign.itpropartner.com) | Live |
| Notarization | Proof API (RON) | Need account |
| Certified mail | LetterStream API (~$8.34/letter) | Need account |
| Payments | Stripe ACH (0.8% capped $5) | Need keys |
| Phone notifications | Twilio SMS | Need account |
| AI analysis | Claude Opus 4.7 via admin-ai | Designed |
| Bot protection | Cloudflare Turnstile invisible | Key set, in form |

## Customer Workflow (full)

### Phase 1 — Intake
- Client lands at debtrecoveryexperts.com or portal
- Fills out intake form: Your Info → Debtor Info → Claim Details → Docs → Terms → Turnstile → Submit
- Uploads supporting documents (contracts, invoices, correspondence)
- Signs Terms of Service + Privacy Policy via DocuSeal
- Auto-generated claim number: DRE-YYYY-NNNN
- Claim enters DRE queue

### Phase 2 — AI Review
- **AI analysis is per claim, not per client.** Each claim gets independent scoring, debtor research, and weakness assessment.
- AI Claim Analysis (Claude Opus 4.7) → score 0-100 + factor breakdown
- AI Debtor Research (ScapringAnt + Sherlock + TX SoS) → skip tracing
- AI Re-analysis on new document upload — score delta tracked in timeline
- Internal team reviews → Approve / Request More Docs / Reject

### Phase 3 — Legal Setup
- LPOA sent via DocuSeal
- Notarized via Proof (RON — Remote Online Notarization)
- DRE now authorized to collect

### Phase 4 — Tiered Recovery
- Tier 1 — Soft Touch: automated email + Stripe ACH link (Day 1-5)
- Tier 2 — Formal Demand: certified mail via LetterStream (Day 7-14)
- Tier 2.5 — Lien Threat: pre-lien notice (Day 15-21) or TX attorney files lien
- Tier 3 — Escalation: final notice (Day 21-30)
- Tier 4 — Legal Action: referral to partner law firm (Day 30+)

### Phase 5 — Settlement & Disbursement
- Debtor pays via Stripe ACH or physical check
- DRE fee deducted per tier schedule
- Costs deducted (notary ~$25-35, certified mail ~$8.34, filing fees ~$250-400)
- Balance disbursed to client via ACH

### Phase 6 — Case Closure (Dual Binders)
- DRE Internal Binder (13 docs including AI analysis, research, internal notes)
- Client Package (5 docs — excludes AI analysis, research, notes)
- Evidence archive (original uploads)

## Fee Structure (proposed)

| Tier | DRE Fee | Client Gets |
|------|---------|-------------|
| 1 — Soft Touch | 20-25% | 75-80% |
| 2 — Demand | 30% | 70% |
| 3 — Escalate | 33% | 67% |
| 4 — Legal | 10% DRE + 25% firm | 65% |

## Approval Workflow

- **Appovers:** Germaine + Tony — both must sign off
- **Anita:** Read-only — can view, cannot approve
- Approval status per claim: "Pending Germaine" / "Pending Tony" / "Acknowledged"
- Hourly reminder cron for unacknowledged approvals
- Approve & Continue button has hover tooltip explaining dual-approval workflow

## Client Portal View

Logged-in client sees:
1. Welcome + member since date
2. Summary cards: active claims, recovered count, total recovered $, in progress $
3. Active claim with 4-step tier progress indicator (circles + centered labels + connecting lines)
4. Past claims: outcome badges (Recovered / Uncollectible), Download binders
5. Submit New Claim button
6. Recovery Stats (claims filed, success rate, avg time, fees paid, net)
7. Recent Disbursements

## Professional Features

- **Change History** — every edit tracked (who, what field, old→new, timestamp, reason)
- **Case Aging Dashboard** — monitors days in tier vs target (red/amber/green)
- **Debtor Payment Page** — standalone landing page for phone-in payments
- **Settlement agreement templates** pre-built in DocuSeal
- **Watermark** on displayed docs: "CONFIDENTIAL - DRE CASE FILE - XXXXXX"
- **Batch small claims** under $2K into one recovery
- **Referral tracking** — 5% off next claim for referrals

## Cost Per Claim

| Item | Cost |
|------|------|
| RON Notarization | ~$25-35 |
| Identity Verification | ~$4 |
| Certified Mail | ~$8.34 |
| Processing (ACH) | ~$5 max |
| **Total** | **~$37-48** |

These costs passed to debtor or deducted from proceeds.

## Infrastructure

- All mockups at `/root/portal-mockup/`, served at `https://app.itpropartner.com/`
- Signing at `sign.itpropartner.com` (Caddy → DocuSeal)
- Vehicle data at `core.itpropartner.com/vehicles.json`
- A records needed: `portal.debtrecoveryexperts.com` (Cloudflare)
- API webhooks: DocuSeal → `https://debtrecoveryexperts.com/api/webhooks/docuseal`

## Design Conventions

- **Customer pages:** Light theme (#f8fafc bg, white cards), amber CTAs, ScrapingAnt-inspired split-screen
- **Internal pages:** Dark theme (#0f172a bg, #1e293b cards), amber/blue/green status badges
- **Approval UI:** Amber badge in nav with hover detail, color-coded per partner status
- **Tier progress:** 4-step flex column — circles + labels centered below + connecting lines
- **Turnstile:** Invisible mode, referenced in privacy policy

## Actions Needed

- [ ] Proof.com account (online notarization)
- [ ] LetterStream account (certified mail)
- [ ] Stripe Connect keys (ACH payments)
- [ ] Twilio account (SMS notifications)
- [ ] Law firm partner (Tier 4 litigation)
- [ ] A record `portal.debtrecoveryexperts.com` on Cloudflare
- [ ] Kanary setup for Germaine ($84/yr)
- [ ] TX attorney review of ToS, Privacy Policy, Compliance Manual

## Portal Mockups

All at `app.itpropartner.com/`:
- `debt-recovery.html` — Claim intake form (split-screen, Turnstile)
- `dre-client-dashboard.html` — Client portal (white, tier progress, stats)
- `dre-dashboard.html` — Internal queue (dark, AI analysis, change history)
- `dre-case-aging.html` — Case aging (dark, days-in-tier tracking)
- `dre-pay.html` — Debtor payment (minimal, no nav)
- `dre-fee-calculator.html` — Fee estimate (live calculation)