README.md

metadata

title: Courtmitra
emoji: 🚀
colorFrom: red
colorTo: indigo
sdk: docker
pinned: false

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

# 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

# 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