README.md

# 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