ruby-docchase

byAkhil K

# DocChase — MVP Build Prompt Build **DocChase**, a production-ready MVP for Indian CA firms. ## PRODUCT DocChase is a **WhatsApp-native document collection and follow-up SaaS**. A CA creates a client and assigns a checklist for GST filing, ITR filing, audit, accounting, or custom work. DocChase sends the checklist through WhatsApp, receives documents from the client, identifies and classifies them against that client's pending checklist, stores them securely, updates their status, automatically reminds the client about missing documents, stops reminders when complete, and escalates unresolved cases to the CA. **Core promise:** "Stop chasing clients for documents. DocChase automatically requests, collects, organizes and follows up through WhatsApp." Build only this workflow. Keep the product simple. ## DO NOT BUILD No client upload portal, email/SMS, tax calculations, GST/ITR filing, accounting, invoicing, billing, payroll, full CRM, lead management, marketing automation, mobile app, AI tax/legal advice, or unnecessary analytics. ## STACK Use: * Next.js/React + TypeScript * Node/TypeScript backend * Supabase PostgreSQL + Auth + private Storage * Twilio WhatsApp API * Vision-capable AI such as Gemini * Simple cron/scheduled job First inspect the existing **ShopSync/Retail_Agent** project. Reuse proven Twilio, Supabase, auth, storage and webhook patterns where useful, but do not copy retail-specific business logic. --- # DATABASE Create a multi-tenant schema: ```text id="yqj0w1" firms: id, name, phone_number, created_at users: id, firm_id, name, role, phone, created_at clients: id, firm_id, name, phone, alt_phones, status, created_at checklist_templates: id, firm_id, task_type, name, document_types, created_at checklists: id, firm_id, client_id, template_id, task_label, created_at, due_date, status checklist_items: id, checklist_id, doc_type, label, status, received_at, file_url, confidence_score, manually_confirmed_by, created_at, updated_at reminders: id, checklist_id, schedule_days, last_sent_at, next_send_at, reminders_sent_count, paused, created_at message_log: id, firm_id, client_id, checklist_id, direction, message_type, content, twilio_sid, created_at escalations: id, checklist_id, reason, created_at, resolved_at, resolved_by ``` Statuses: `checklists: pending/complete/escalated` `items: missing/received/rejected` `messages: in/out` `escalations: no_response_after_max_reminders/classification_uncertain/client_disputed/unassigned_sender` `alt_phones` is JSONB. `document_types` is JSONB, e.g.: ```json id="zjwk5q" [{"doc_type":"bank_statement","label":"Bank Statement","required":true}] ``` Default reminder schedule: `[1,3,7]`. --- # SECURITY This is multi-tenant. Every business query MUST be scoped by `firm_id`. Use Supabase RLS. Firm A must never access Firm B's clients, documents, checklists, messages or escalations. Use private Storage and signed URLs: `/firms/{firm_id}/clients/{client_id}/documents/{document_id}` Never expose service-role keys in frontend. --- # CORE WORKFLOW ### 1. CA creates checklist CA logs in → creates/selects client → selects template → edits required documents → creates checklist. Seed templates for: **GST:** Sales invoices, Purchase invoices, Bank statement, GST sales report, GST purchase report. **ITR:** PAN, Aadhaar, Form 16, Bank statement, Investment proofs. **Audit:** Bank statements, Sales invoices, Purchase invoices, Expense records, Fixed asset details. Templates must be editable. On checklist creation, send a short WhatsApp request containing required documents. Example: > Hi Ravi ji 👋 GST filing ke liye Bank statement, Purchase invoices aur Sales report chahiye. Aap yahin WhatsApp par bhej sakte ho. Log the outbound message. --- # WHATSAPP WEBHOOK Inbound flow: `WhatsApp → Twilio → webhook → identify client → find active checklist → process message` Verify Twilio signatures. Normalize phone numbers. Search `clients.phone`, then `alt_phones`. If no match, do NOT discard the message. Create an unassigned item and show it to the CA for manual linking. Twilio retries webhooks, so `twilio_sid` must be unique/idempotent. Never process the same webhook twice. Support text, image and PDF/document media. --- # DOCUMENT INTAKE When a client sends a document: `Twilio → identify client → find pending checklist → download media → Supabase Storage → AI classification → confidence gate → update item OR CA review` Twilio media URLs are temporary. Always download and store permanently. Never mark a document received if storage fails. --- # AI CLASSIFICATION AI must classify ONLY against that client's currently **missing checklist items**. Example pending items: `Bank Statement, Purchase Invoice, Sales Invoice` The AI cannot invent other types. Return JSON: ```json id="29m5uw" { "doc_type": "bank_statement", "match_reason": "Appears to be a bank statement.", "alternative_doc_type": "purchase_invoice", "classification_confidence": 0.94 } ``` If no match, return `doc_type: null`. Build classification as an isolated service first and test using real/sample documents: PAN, Aadhaar, bank statements, GST documents, invoices, Form 16, investment proofs and irrelevant files. Do not use AI for database permissions, tenant isolation, reminders, status transitions or duplicate detection. Those are deterministic. --- # CONFIDENCE + REVIEW Initial configurable thresholds: * `>= 0.90` → automatically accept * `0.70–0.89` → CA review * `< 0.70` → CA review Never trust low-confidence classification automatically. If AI fails, times out or returns invalid JSON → CA review with `classification_uncertain`. Create a simple review queue: **Client:** Ravi Traders **File:** IMG_123.jpg **Possible:** Bank Statement 82%, Purchase Invoice 14% Actions: `Accept / Reject / Choose Different Document` Manual confirmation stores `manually_confirmed_by`. --- # DUPLICATES If a checklist item is already `received` and another document arrives for that same slot, NEVER silently overwrite it. Send it to CA review with: `Keep original / Replace / Reject` --- # REMINDERS Default schedule: **Day 1, Day 3, Day 7**. A scheduled job checks: `checklist = pending AND reminders.paused = false AND required missing items exist` Send reminders containing ONLY currently missing documents. Example: > Hi Ravi ji 👋 Purchase invoices and GST report are still pending. Please send them here whenever convenient. Never remind for documents already received. When all required items are received: `checklist.status = complete` `reminders.paused = true` Send a completion message and never remind again. --- # ESCALATION After the final reminder, if required documents remain missing: `create escalation` `reason = no_response_after_max_reminders` `checklist.status = escalated` `reminders.paused = true` Never continue nagging indefinitely. Dashboard must show **Needs Manual Follow-up**. --- # DASHBOARD Keep it mobile-first and minimal. Main view: ```text id="s7m4uo" Ravi Traders GST Filing 3/5 received 🟡 2 missing Patel Enterprises ITR Filing 5/5 received 🟢 Complete Shah & Co GST Filing 2/5 received 🔴 Escalated ``` Filters: `All / Pending / Complete / Escalated / Needs Review` Client page shows: * Client details * Checklist * Missing/received/rejected documents * Uploaded files * Reminder history * Message history * Review items * Escalations CA controls: `Mark received / Mark missing / Reject / Replace / Pause reminders / Resume / Resolve escalation / Link unknown sender` Do not build a full CRM or WhatsApp clone. --- # FILES + SECURITY Use private Supabase Storage and signed URLs. Environment variables: ```text id="0d1p0m" SUPABASE_URL SUPABASE_ANON_KEY SUPABASE_SERVICE_ROLE_KEY TWILIO_ACCOUNT_SID TWILIO_AUTH_TOKEN TWILIO_WHATSAPP_NUMBER AI_API_KEY ``` Provide `.env.example`. Never commit secrets. --- # TESTING Test: 1. Firm isolation/RLS. 2. Twilio webhook idempotency. 3. Primary and alternative phone identification. 4. Unknown sender. 5. Checklist creation. 6. AI restricted to pending checklist items. 7. Low-confidence classification. 8. Duplicate documents. 9. Completion stops reminders. 10. Reminder contains only missing documents. 11. Escalation after maximum reminders. 12. Storage/AI failure handling. Allow reminder schedules to be simulated during development. --- # BUILD ORDER Follow this exact order: **Phase 1:** Database + RLS + Twilio webhook + client identification + message logging. **Phase 2:** Auth + clients + templates + checklists. **Phase 3:** Outbound WhatsApp. **Phase 4:** Document media download + Supabase Storage. **Phase 5:** Isolated AI classification testing. **Phase 6:** Classification + confidence gate + CA review + status updates. **Phase 7:** Reminder + escalation engine. **Phase 8:** Dashboard polish. After every phase: run tests, verify it works, fix errors, then continue. Do NOT build the entire application blindly in one generation. --- # DEVELOPMENT RULES * Do not over-engineer. * Do not invent requirements. * Do not build non-MVP features. * Reuse proven Retail_Agent infrastructure where appropriate. * Database is the source of truth. * AI cannot directly control application state. * Fail safely when uncertain. * Assume webhooks can be duplicated. * Never fake functionality. * Reliability and security matter more than UI polish. ## FINAL MVP The complete flow must work: `CA creates client → assigns checklist → WhatsApp request → client sends document → Twilio webhook → identify client → store file → AI classification → confidence gate → checklist update → reminders for missing items → COMPLETE or ESCALATED` **FIRST ACTION:** Inspect the existing project/repository. Identify reusable Twilio, Supabase, auth, storage and webhook code. Then implement **Phase 1 ONLY**, test it, and report what works before moving to Phase 2.