hermes-skills/skills/devops/debt-recovery-workflow/references/dre-portal-specs.md

# DRE Portal — Technical Specifications
## Internal working document — July 2026

### Claim Numbering
- Format: `DRE-YYYY-NNNN` (e.g. DRE-2026-0001)
- Auto-generated on claim submission

### Client ID
- Format: `CLT-YYYY-NNNN` (e.g. CLT-2026-0001)
- Generated on account creation

### Closed Case Binders
On case close, two PDF binders are auto-generated:

**Binder 1 — DRE Internal:**
  DRE-YYYY-NNNN_CLOSED_DRE.pdf
  Includes: intake, evidence, AI analysis, AI debtor research, AI weakness analysis,
  internal notes, signed/notarized LPOA, certified mail receipts, communication log,
  settlement, fee disclosure, payment confirmation

**Binder 2 — Client Package:**
  DRE-YYYY-NNNN_CLOSED_Client.pdf
  Includes: claim summary, signed/notarized LPOA, settlement/payment confirmation,
  fee statement. EXCLUDES: AI analysis, debtor research, internal notes.

**Evidence Archive:**
  DRE-YYYY-NNNN_evidence.zip — original uploaded documents

### Full Workflow

#### Phase 1 — Intake
- Client submits claim at debtrecoveryexperts.com
- Intake form fields: your info (name, business, email, phone) → debtor info (business, contact, email, phone, address) → claim details (amount, description, state, debt type) → document upload
- Terms of Service signed via DocuSeal
- Turnstile bot protection (invisible mode, Cloudflare)
- Claim auto-numbered and enters DRE queue

#### Phase 2 — AI Review
- AI Claim Analysis (Claude Opus 4.7) → score + weakness report
- AI Debtor Research (ScrapingAnt + Sherlock + TX SoS) → skip tracing, asset scan, legal history
- Team reviews → Approve / Request More Docs / Reject
- Additional docs uploaded mid-process trigger AI re-analysis with score delta tracked

#### Phase 3 — Legal Setup
- LPOA sent to client via DocuSeal
- Client signs → notarized via Proof (online RON)
- DRE now authorized to collect

#### Phase 4 — Tiered Recovery
- Tier 1: Soft Touch — email + ACH link (Day 1-5)
- Tier 2: Formal Demand — certified mail via LetterStream (Day 7-14)
- Tier 2.5: Lien Threat — pre-lien notice for construction claims (Day 15-21)
- Tier 3: Escalation — final notice (Day 21-30)
- Tier 4: Legal Action — referral to partner law firm (Day 30+)
- 4-step tier progress indicator on client dashboard (visual circles with labels, colored by completion)

#### Phase 5 — Settlement
- Payment collected via Stripe ACH
- DRE fee deducted per tier schedule
- Costs deducted (notary, certified mail, filing fees)
- Balance disbursed to client
- Case closed → two binders generated

### Fee Structure (proposed)
- Tier 1: 20-25%
- Tier 2: 30%
- Tier 2.5: 30% (+ attorney if lien filed)
- Tier 3: 33%
- Tier 4: 10% DRE referral + 25% law firm

### Search & Document Retrieval
Cases are searchable in the portal via database fields:
- Claim number, client name, debtor name, amount, status, date range
- Tags (e.g. "construction", "lien filed", "litigated", "debtor paid Tier 2")
- Key flags from AI analysis

On case close, PDF text is extracted and stored in the database for full-text search.
Future: Paperless-ngx if volume exceeds 500+ cases.

### Audit Trail (Change Tracking)
Any edit to a claim submission is tracked with a full history:
- What field was changed (old value → new value)
- Who made the change (user name or "system" for automated updates)
- When the change was made (timestamp)
- Why the change was made (optional note field)

The audit log is visible in the DRE internal dashboard under each claim. Edits allowed on open claims only. Closed claims are read-only. Audit trail included in the DRE Internal Binder on case close.

Color coding in audit log:
- DRE team changes: amber/gold
- System changes: blue
- Client actions: green

### Document Upload During Recovery
Clients can upload additional documents at any point during the active recovery process via their portal. Each upload can include a reason/context note. When new docs arrive, the AI automatically re-analyses the claim and updates the score. The re-analysis event is logged in both the timeline and the change history with the score delta (e.g. "Score: 78 → 82").

### Repeat Clients
Clients create an account on first claim. On return:
- ToS already on file (signed once)
- Client info pre-filled on new claims
- Dashboard shows: active cases, past cases with outcomes, payment history
- Can download their own case binders
- Optional loyalty pricing after 3+ claims (e.g. 25% vs 30%)

### Client Portal View (after login)
- Active Cases: claim number, debtor, amount, current tier with 4-step progress indicator
- Past Cases: claim number, debtor, amount, outcome (Recovered / Uncollectible) with Download button
- [Submit New Claim] button
- [Download Case Binders] for closed cases
- [Payment History] — all disbursements received

### Approval Workflow
When a DRE team member clicks "Approve & Continue", the partner (Tony) receives a notification to acknowledge. The case holds at approval step until both partners have signed off. The approval status indicator appears in the header nav amber badge.

### Turnstile Anti-Bot
Form uses Cloudflare Turnstile (invisible mode). Site key and secret key stored in `.env`. Privacy policy includes Turnstile Privacy Addendum reference.

### Debtor Research Sources
- LinkedIn (via ScrapingAnt headless Chrome)
- Public property records
- Texas Secretary of State business search (status, registered agent, officers, filing compliance)
- Court records / legal history
- Asset scans
- Output: sources found, estimated revenue, assets, prior judgments, risk assessment

### Required Services
- DocuSeal: ✅ deployed at sign.itpropartner.com
- Proof.com: ❌ need account (online notarization)
- LetterStream: ❌ need account (certified mail)
- Stripe Connect: ❌ need keys (ACH payments)
- Law firm partner: ❌ need referral agreement (litigation)