Spaces:
Sleeping
Sleeping
| 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 | |
| ```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 | |