docs: add comprehensive README for CourtMitra MissionOS

README.md

@@ -0,0 +1,144 @@
+# CourtMitra MissionOS
+
+**Citizen-side grievance + legal-action autopilot for India.** A citizen describes a problem once (WhatsApp, Telegram, or browser); the system turns it into a **mission**, builds the evidence file, grounds it in Indian law/procedure, picks an official route, drafts + sends approved actions, follows up, and records the outcome.
+
+## Architecture
+
+```
+apps/{web, api, worker}
+packages/{domain, ports, adapters, db, contracts, prompts, ui}
+```
+
+| Layer | Tech | Role |
+|---|---|---|
+| `apps/web` | Next.js (App Router), i18n | Multi-tab mission UI, public case pages, ledger |
+| `apps/api` | NestJS + Fastify | REST endpoints, action preview/consent/execution |
+| `apps/worker` | Inngest | Async workflow engine: intake, evidence, route-plan, action execution, followups |
+| `packages/domain` | Pure TS | Entities, policies (`canResolve`), use-cases — zero framework deps |
+| `packages/ports` | TS interfaces | Adapter contracts for channels, storage, LLM, redaction |
+| `packages/adapters` | Various | Resend (email), Telegram, WhatsApp, social copy-ready |
+| `packages/db` | Postgres + Drizzle ORM | Schema, migrations, seeds, materialized views |
+| `packages/contracts` | Zod + OpenAPI | Single source of truth for all API I/O and LLM output shapes |
+| `packages/prompts` | Versioned prompts | Evals included; no inline prompts in controllers |
+| `packages/ui` | shadcn/ui + Tailwind | Shared UI components |
+
+## Platform Features
+
+### Lifecycle (10 states)
+`route_plan_ready` → `actions_preview_ready` → `actions_awaiting_consent` → `action_executing` → `user_confirmed_external_submission` → `waiting_for_response` → `resolver_reply_received` → `resolution_claimed` → `resolved`
+
+Plus: `created`, `intake_in_progress`, `needs_user_input`, `human_review_required`, `facts_confirmed`, `closed_unresolved`, `paused`, `blocked`, `failed`
+
+### Mission Page (6 tabs)
+1. **Overview** — current status, next action, timeline
+2. **Facts** — extracted evidence timeline, missing info questions
+3. **Route** — route plan steps with legal citations
+4. **Action** — preview, approve, consent, execute, confirm external
+5. **Follow-up** — waiting timer, social media escalation (X/Threads copy-drafts)
+6. **Outcome** — resolution filing, ledger publication
+
+### Security & Safety
+- **Rank-guarded state machine** — no snapshot can regress the mission lifecycle (`STATE_RANK`)
+- **Consent-first** — every send is gated by a hash-verified consent grant
+- **Redaction** — Presidio-based PII redaction before any public output
+- **Stop-and-refer** — emergency/criminal flags trigger `human_review_required`
+- **Idempotency keys** — all write endpoints and webhooks are idempotent
+
+### Social Proof & Leverage
+- **EscalateSocialCard** — copy-ready X.com/Threads drafts for immediate public posting
+- **Swarms** — entity resolution tracks repeat offenders (Flipkart, Amazon, Paytm, etc.)
+- **Public Case Pages** — private-link anonymized summaries for social sharing
+- **Ledger** — `ledger_stats_view` + `repeat_offender_view` materialized views
+
+### Demo Data
+- 10+ realistic missions across all lifecycle states, domains (consumer, payment, cyber_fraud), and states (Delhi, Maharashtra, Karnataka, etc.)
+- 7 swarms with aggregated case counts
+- 1 takedown request (Meta/Instagram)
+- 5 public case pages with anonymized summaries
+- 8 case lookups and 8 scheduled follow-ups
+
+## Quick Start
+
+```bash
+# Prerequisites
+node >= 20
+pnpm >= 10
+docker  (for local Postgres)
+
+# Install
+pnpm install
+
+# Start infrastructure (Postgres + Redis)
+pnpm infra:up
+
+# Run migrations
+pnpm db:migrate
+
+# Seed demo data
+pnpm db:seed
+
+# Start dev servers (web + api + worker)
+pnpm dev
+```
+
+Open `http://localhost:3000` in your browser.
+
+## Commands
+
+| Command | Description |
+|---|---|
+| `pnpm dev` | Run web + api + worker in parallel |
+| `pnpm build` | Build all packages |
+| `pnpm typecheck` | `tsc --noEmit` across all 10 packages |
+| `pnpm lint` | ESLint with dependency-boundary rules |
+| `pnpm test` | Vitest (unit + integration) |
+| `pnpm test:contracts` | Zod/OpenAPI contract validation |
+| `pnpm db:migrate` | Run Drizzle migrations |
+| `pnpm db:seed` | Seed route rules + curated citations |
+| `pnpm infra:up` | Docker compose: Postgres + Redis |
+| `pnpm infra:down` | Stop Docker containers |
+
+## Environment
+
+Copy `infra/.env.example` to `infra/.env` (see `infra/.env` for current values). Key variables:
+
+| Variable | Required | Description |
+|---|---|---|
+| `DATABASE_URL` | Yes | Postgres connection string |
+| `RESEND_API_KEY` | For email | Resend email API key |
+| `TELEGRAM_BOT_TOKEN` | For Telegram | Telegram bot token |
+| `WHATSAPP_*` | For WhatsApp | WhatsApp Cloud API credentials |
+| `X_API_*` | For X posting | X/Twitter API v2 credentials |
+| `OPENAI_API_KEY` | For LLM | OpenAI / OpenRouter API key |
+
+## Key Design Decisions
+
+- **Hexagonal architecture** — domain is pure TS with zero framework imports
+- **Everything external is an Action** — adapters never called directly from workflows
+- **State machine is rank-guarded** — no transition can regress the lifecycle
+- **Contracts-first** — Zod schemas in `packages/contracts` are single source of truth; API routes and frontend import them
+- **Database transactions + events** — all mutations go through Drizzle transactions; mission events are append-only audit
+- **No fake submissions** — `proofState` accurately reflects real delivery status
+- **No legal claim without cited source** — every legal statement carries `cited_chunk_ids`
+- **Public pages are private-link only** — no indexing, no defamation risk
+- **i18n** — English + Hindi (`next-intl`), language switcher in header
+
+## Loading Demo Data
+
+```bash
+# Seed all demo missions with full lifecycle data
+pnpm exec tsx packages/db/src/seeds/demo-data.ts
+```
+
+This creates 10+ missions across all lifecycle states, swarms, takedown requests, public case pages, and ledger entries. It preserves existing user missions.
+
+## Non-Goals (Phase 2)
+
+- Complaint swarm dashboard
+- Live social auto-publishing (API keys needed)
+- Company resolver portal
+- Qdrant/rerank RAG upgrade
+- ASR/voice transcription
+- Supervised Playwright portal automation
+- eCourts real-time case scraping
+- AI-run public social account