Quick Start
ββ
Features
ββ
Architecture
ββ
API Routes
ββ
Modules
ββ
Configuration
ββ
Contributing
CrimeGPT is a next-generation AI-powered platform engineered for modern Law Enforcement in India. It transforms the traditional, paper-heavy crime documentation process into a streamlined, digital-first workflow driven by Retrieval-Augmented Generation (RAG), multi-model LLM routing, and a full-stack React + FastAPI architecture.
Legal Framework: Optimized for BNS 2023 (Bharatiya Nyaya Sanhita), BNSS (Bharatiya Nagarik Suraksha Sanhita), BSA (Bharatiya Sakshya Adhiniyam), and IT Act 2000
| Feature | Traditional Method | CrimeGPT Advantage |
|---|---|---|
| FIR Generation | 2β3 hours manual drafting | < 30 seconds AI-structured drafts |
| Legal Research | Manual book lookups | Instant BNS 2023 RAG Intelligence |
| Documents | Manual typing of each form | Auto-generated Chargesheets, Remand, Seizure, etc. |
| Evidence | Physical logbooks | Immutable digital chain-of-custody + SHA-256 |
| Intelligence | Manual link detection | AI-driven MO pattern recognition |
| Interoperability | Siloed systems | CCTNS / BharatPol mock integration |
The installer handles all dependencies, Python venv, npm packages, Docker infrastructure, and database schemas:
git clone git@github.com:XploitMonk0x01/crimegpt.git
cd crimegpt
./install.sh
./start.shThe install.sh script will:
- β Verify prerequisites (git, docker, npm, python3, docker-compose)
- β Prompt for Groq API key (optional β for LLM features)
- β Launch PostgreSQL, Redis, and ChromaDB via Docker
- β Set up Python virtual environment and install dependencies
- β Install frontend npm packages
- β Initialize database schema and seed demo data
docker compose up -dcd backend
python -m venv venv && source venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
# Edit .env with your GROQ_API_KEY (get one at https://console.groq.com)
python init_db.py
python seed_demo.py
uvicorn app.server:app --host 127.0.0.1 --port 8000 --reloadcd frontend
npm install
npm run dev -- --host| Role | Badge Number | Security PIN |
|---|---|---|
| Admin | PN-2024-ADMIN |
1234 |
| Station Head (SHO) | PN-2024-SHO |
1234 |
| Investigating Officer (IO) | PN-2024-IO |
1234 |
The app will be available at http://localhost:5173.
Tip
The API docs (Swagger UI) are available at http://127.0.0.1:8000/docs when DEBUG=true.
- Natural language incident input β structured AI FIR draft with NER extraction
- Sequential FIR numbering:
FIR-00001,FIR-00002, ... - Complainant & accused details, location, applicable BNS/IT sections
- Persistent local storage β works offline; syncs when backend is available
- Country-aware phone input with flag selector
- Full FIR lifecycle: draft β submit β approve/reject
- Real-time Q&A powered by Groq LLM (multi-model routing)
- Trained on BNS 2023, IT Act 2000 corpora via RAG pipeline
- Hybrid retrieval: ChromaDB vector search + BM25 lexical search fused via Reciprocal Rank Fusion
- Markdown-formatted responses with section citations
- RAG safety controls: prompt injection stripping, PII redaction (configurable)
- Configurable allowed domains for URL-based corpus ingestion
- Secure digital evidence upload tied to specific FIRs
- SHA-256 integrity hashing on every upload
- Immutable chain of custody β append-only JSONB audit trail
- File type detection & image gallery preview
- Integrity verification endpoint
- Role-restricted upload (Inspector+)
- Role-aware: IO sees personal stats; SHO/Admin see station-wide metrics
- Live FIR counts: Total, Draft, Submitted, Approved, Rejected
- Recent FIR activity feed with status badges
- Pending approvals queue (SHO/Admin)
- Audit log viewer (SHO/Admin)
- Crime analytics & trend data
- AI-powered pattern detection across multiple FIRs
- Semantic similarity scoring using vector embeddings
- Formal case linking by Inspector+ officers
- MO (Modus Operandi) cluster analysis
- Find similar cases by configurable threshold (default 0.70)
- AI-powered generation of 7 legal document types from FIR data:
| Document Type | Description |
|---|---|
chargesheet |
Purvani/Final Report under BNSS |
medical_letter |
Medical Treatment Letter for victims |
remand_request |
Police Custody Remand Request |
seizure_receipt |
Seizure & Search Receipt (Panchanama) |
court_custody_letter |
Court Custody Transfer Letter |
accused_panchanama |
Accused Observation Panchanama |
face_id_form |
Accused Face Identification Form |
- PDF export with metadata
- Version history β every generation creates a snapshot
- Multilingual document generation (English, Hindi, Gujarati)
- Timeline-based investigation diary tied to each FIR
- 12 entry types: complaint received, FIR registered, investigation started, witness examined, evidence seized, spot visit, arrest made, remand requested, chargesheet filed, court hearing, etc.
- Ordered timeline with officer attribution
- Entry deletion (Inspector+ only)
- Generate LERS-compliant law enforcement requests for:
- Meta / Facebook β Emergency Disclosure, Account Preservation, Subscriber & IP Log
- WhatsApp β Emergency Disclosure, Account Preservation
- Instagram β Emergency Disclosure, Account Preservation
- Telegram β Emergency Disclosure, Account Preservation
- X (Twitter) β Emergency Disclosure, Account Preservation
- Generates legally-formatted notice templates with:
- Section 94 BNSS / Section 91 CrPC legal authority
- Platform-specific SLA data
- Reference IDs and digital attestation
- Searchable FIR autocomplete for reference numbers
- Live demo credentials auto-filled for demo mode
- JWT-based authentication with access + refresh token rotation
- Redis-backed session management with logout invalidation
- 4-tier Role-Based Access Control:
| Capability | Constable | IO | SHO | Admin |
|---|---|---|---|---|
| FIR: create / edit | β | β | β | β |
| FIR: approve / reject | β | β | β | β |
| Evidence: upload | β | β | β | β |
| Case: link | β | β (Inspector) | β | β |
| Diary: delete | β | β | β | β |
| Officer: register | β | β | β | β |
| Audit: view | β | β | β | β |
| RAG corpus: ingest | β | β | β | β |
- Demo bypass mode for development (no DB query for mock users)
- Mock CCTNS National Grid FIR sync with SHA-256 payload verification
- BharatPol criminal record lookup with deterministic mock responses
- CCTNS Reference ID generation and sync status API
- Audit-logged sync events
- Speech-to-text via Groq Whisper (
whisper-large-v3-turbo) - Translation between English β Hindi β Gujarati
- Audio transcription with 25MB file limit, multiple format support
- Configurable language for document generation
- Append-only audit log table β no updates or deletes
- Tracks: LOGIN, LOGOUT, FIR_CREATE, FIR_EDIT, FIR_SUBMIT, FIR_APPROVE, FIR_REJECT, FIR_SEARCH, FIR_EXPORT_PDF, CCTNS_SYNC, DOCUMENT_GENERATE, DOCUMENT_EXPORT_PDF, DIARY_ENTRY_ADD, DIARY_ENTRY_DELETE, EVIDENCE_UPLOAD, EVIDENCE_ACCESS, EVIDENCE_VERIFY, CASE_LINK, LEGAL_QUERY, TRANSLATE
- Each entry stores: officer, action, resource type/ID, details (JSONB), IP address, user agent, timestamp
- Eager-loaded officer metadata (badge_no, name) for display
crimegpt/
βββ frontend/ # React + Vite SPA
β βββ src/
β β βββ components/ # 11 UI Components
β β β βββ Login.jsx # Auth entry point
β β β βββ Dashboard.jsx # Role-based command center
β β β βββ FIRAutomator.jsx # AI FIR drafting
β β β βββ LexBot.jsx # Legal Q&A assistant
β β β βββ Vault.jsx # Evidence management
β β β βββ CaseLinkage.jsx # Cross-case pattern analysis
β β β βββ CaseDiary.jsx # Investigation timeline
β β β βββ DocumentGenerator.jsx # Legal doc auto-generation
β β β βββ LERSPortal.jsx # LERS cyber request platform
β β β βββ Sidebar.jsx # RBAC-aware navigation
β β β βββ UserSettings.jsx # Profile & preferences
β β βββ services/
β β β βββ api.js # Axios service layer (auth, fir,
β β β # evidence, legal, nlp, docs,
β β β # diary, search, cctns, lers)
β β βββ store/
β β βββ authStore.js # Zustand auth state
β β βββ firStore.js # Zustand FIR state + localStorage
β βββ package.json
β βββ vite.config.js
β
βββ backend/ # FastAPI Python API
β βββ app/
β β βββ routes/ # 12 API routers
β β β βββ authRoutes.py # POST /login, /refresh, /logout, /register
β β β βββ firRoutes.py # POST /generate, /submit, PATCH /{id}/edit, ...
β β β βββ legalRoutes.py # POST /query, GET /sections/search, /corpus/*
β β β βββ evidenceRoutes.py # POST /upload, GET /fir/{id}, /{id}/custody...
β β β βββ caseRoutes.py # GET /similar/{id}, POST /link, GET /clusters
β β β βββ nlpRoutes.py # POST /transcribe, /translate, GET /languages
β β β βββ dashboardRoutes.py # GET /officer, /inspector, /audit-logs, /analytics
β β β βββ documentRoutes.py # GET /types, POST /generate, /export-pdf, /versions
β β β βββ caseDiaryRoutes.py # GET /types, POST /{firId}/entry, DELETE /entry/{id}
β β β βββ searchRoutes.py # GET /search?q=...
β β β βββ cctnsRoutes.py # POST /sync-fir/{id}, GET /verify-person, /status/{id}
β β β βββ lersRoutes.py # POST /generate, GET /platforms, /request-types
β β βββ controllers/ # Request/response orchestration
β β βββ services/ # Business logic (14 services)
β β βββ models/ # SQLAlchemy ORM (7 models)
β β βββ schemas/ # Pydantic validation
β β βββ middleware/ # Auth, RBAC, error handler, rate limiter
β β βββ config/ # Pydantic Settings (env-based)
β β βββ types/ # Enums, response types
β β βββ utils/ # JWT, hashing, hybrid_retrieval, text_extraction
β β βββ main.py # App factory
β βββ corpus/ # Legal corpus for RAG ingestion
β β βββ bns_2023/ # Bharatiya Nyaya Sanhita 2023
β β βββ it_act_2000/ # Information Technology Act 2000
β βββ init_db.py # DB schema initializer
β βββ seed_demo.py # Demo data seeder
β βββ requirements.txt
β
βββ docker-compose.yml # PostgreSQL, Redis, ChromaDB
βββ install.sh # Automated setup & dependency installer
βββ start.sh # Application runtime launcher
βββ docs/ # Documentation
β βββ day3/execution-plan.md # Day 3 execution pack
β βββ demo-checklist.md # Demo walkthrough checklist
β βββ document-compliance-matrix.md # PS document mapping
β βββ eval/legal-benchmark.json # Legal evaluation benchmark
β βββ samples/ # 7 document sample outputs
βββ README.md
| Layer | Technology |
|---|---|
| Frontend | React 19, Vite 8, Tailwind CSS 4, Framer Motion |
| State | Zustand + localStorage (offline FIR persistence) |
| Backend | FastAPI, Python 3.11+ (supports 3.13) |
| Database | PostgreSQL 15 (Docker) |
| Cache | Redis 7 (Docker) |
| Vector Store | ChromaDB (Docker) |
| LLM Provider | Groq API (Llama 3.3 70B / Llama 3.1 8B) |
| LLM Local | Ollama (Mistral 7B) |
| STT | Groq Whisper (whisper-large-v3-turbo) |
| Auth | JWT (access + refresh) + Redis session management |
| Search | Hybrid BM25 + ChromaDB vector (Reciprocal Rank Fusion) |
| Model | Table | Key Fields |
|---|---|---|
| Officer | officers |
badge_no, role (constable/inspector/station_head/admin), station_id |
| FIR | firs |
fir_no, complainant (JSONB), accused (JSONB), sections (TEXT[]), status |
| Evidence | evidence |
fir_id, sha256_hash, chain_of_custody (JSONB[]), metadata_json |
| CaseLink | case_links |
fir_id_a, fir_id_b, similarity_score, link_reason |
| AuditLog | audit_logs |
action, resource_type, resource_id, details (JSONB), ip_address |
| CaseDiaryEntry | case_diary_entries |
fir_id, entry_type, title, description, entry_date |
| DocumentVersion | document_versions |
fir_id, document_type, version_no, content, metadata |
DRAFT β SUBMITTED β APPROVED
β
REJECTED
All routes are mounted under /api/v1 and require JWT authentication (except /health).
| Method | Endpoint | Description | Access |
|---|---|---|---|
| POST | /login |
Authenticate with badge_no + pin | Public (rate-limited) |
| POST | /refresh |
Rotate refresh token | Public (rate-limited) |
| POST | /logout |
Invalidate session | Authenticated |
| GET | /me |
Current officer profile | Authenticated |
| POST | /register |
Register new officer | Admin/SHO |
| Method | Endpoint | Description |
|---|---|---|
| POST | /generate |
AI draft from incident narrative |
| POST | /submit |
Submit FIR with full data |
| GET | /list |
List FIRs (filterable by status, paginated) |
| GET | /{id} |
Get FIR by ID |
| PATCH | /{id}/edit |
Edit draft FIR |
| POST | /{id}/review |
Approve/reject FIR (SHO/Admin) |
| Method | Endpoint | Description |
|---|---|---|
| POST | /query |
RAG-powered legal Q&A |
| GET | /sections/search |
Search legal sections by keyword |
| POST | /corpus/ingest |
Ingest corpus into vector store (Admin) |
| POST | /corpus/ingest-urls |
Ingest URLs into vector store (Admin) |
| GET | /corpus/stats |
Vector store statistics |
| Method | Endpoint | Description |
|---|---|---|
| POST | /upload |
Upload evidence file (Inspector+) |
| GET | /fir/{fir_id} |
List evidence for a FIR |
| GET | /{id}/download |
Download evidence file |
| GET | /{id}/custody |
Get custody chain |
| GET | /{id}/verify |
Verify SHA-256 integrity |
| Method | Endpoint | Description |
|---|---|---|
| GET | /similar/{fir_id} |
Find semantically similar cases |
| POST | /link |
Formally link two cases (Inspector+) |
| GET | /clusters |
MO cluster analysis |
| Method | Endpoint | Description |
|---|---|---|
| POST | /transcribe |
Speech-to-text (Groq Whisper) |
| POST | /translate |
Translate text (en/hi/gu) |
| GET | /languages |
List supported languages |
| Method | Endpoint | Description | Access |
|---|---|---|---|
| GET | /officer |
Personal dashboard | Authenticated |
| GET | /inspector |
Station-wide dashboard | Inspector+ |
| GET | /audit-logs |
Immutable audit trail | SHO/Admin |
| GET | /analytics |
Crime analytics | Authenticated |
| Method | Endpoint | Description |
|---|---|---|
| GET | /types |
List document types |
| POST | /generate |
Generate document from FIR data |
| POST | /export-pdf |
Export as downloadable PDF |
| GET | /{fir_id}/versions |
List document versions |
| GET | /versions/{id} |
Get specific version |
| Method | Endpoint | Description |
|---|---|---|
| GET | /types |
List entry types |
| POST | /{fir_id}/entry |
Add diary entry |
| GET | /{fir_id} |
Get full case diary |
| DELETE | /entry/{id} |
Delete entry (Inspector+) |
| Method | Endpoint | Description |
|---|---|---|
| GET | / |
Full-text FIR search |
| Method | Endpoint | Description |
|---|---|---|
| POST | /sync-fir/{fir_id} |
Sync FIR to CCTNS national grid |
| GET | /verify-person |
BharatPol criminal record lookup |
| GET | /status/{fir_id} |
CCTNS sync status |
| Method | Endpoint | Description |
|---|---|---|
| POST | /generate |
Generate LERS notice |
| GET | /platforms |
List supported platforms |
| GET | /request-types |
List request types |
| Method | Endpoint | Description |
|---|---|---|
| GET | /health |
Service health check |
Role-aware operational overview. IOs see their own FIRs and case diary summaries. SHOs and Admins get station-wide metrics, pending approvals, recent FIR activity across all officers, audit logs, and crime trend analytics.
Paste or speak an incident narrative. The AI fills in structured fields β complainant details, accused info, incident location, applicable BNS/IT sections β and generates a formatted FIR. Save it and it immediately appears in the dashboard. Full lifecycle: draft β submit (to SHO) β approve/reject.
Type any legal question in plain English (or Hindi/Gujarati). LexBot queries the BNS 2023 and IT Act 2000 corpora via hybrid BM25 + ChromaDB vector search, then generates section-accurate, cited answers. Safety controls strip prompt injection attempts.
Upload digital evidence files linked to specific FIRs. Each file is SHA-256 hashed on upload. Every access is logged in an immutable chain-of-custody. View uploaded images in a gallery, verify integrity, and track custody history.
AI-powered pattern detection across the FIR database. The system identifies semantically similar cases using vector embeddings, scores them, and presents potential links. Inspector+ officers can formally link cases and view MO clusters.
AI auto-generates 7 types of legal documents β Chargesheet, Medical Letter, Remand Request, Seizure Receipt, Court Custody Letter, Accused Panchanama, and Face ID Form β populated from FIR data. Supports PDF export with version history snapshots.
Timeline-based digital investigation diary. Officers log each investigative action (complaint, spot visit, witness exam, arrest, etc.) in chronological order, building a complete case history from FIR to chargesheet.
Generate Law Enforcement Request System (LERS) compliant legal notices for Meta, WhatsApp, Instagram, Telegram, and X. Supports Emergency Disclosure, Account Preservation, and Subscriber & IP Log requests under Section 94 BNSS / Section 91 CrPC.
# Application
APP_NAME=CrimeGPT
APP_VERSION=0.1.0
DEBUG=true
API_PREFIX=/api/v1
# PostgreSQL (Docker: host port 5433 β container 5432)
DATABASE_URL=postgresql+asyncpg://crimegpt:crimegpt_pass@localhost:5433/crimegpt_db
# Redis
REDIS_URL=redis://localhost:6379/0
# JWT Auth
JWT_SECRET=change-me-to-a-real-secret-in-production
JWT_EXPIRY_HOURS=8
REFRESH_TOKEN_EXPIRY_DAYS=7
# LLM Provider
GROQ_API_KEY=your_groq_api_key_here
# Multi-model routing β each task uses the optimal model
GROQ_MODEL_PRIMARY=meta-llama/llama-4-scout-17b-16e-instruct # FIR drafting, legal Q&A
GROQ_MODEL_FAST=llama-3.1-8b-instant # NER, classification
GROQ_MODEL_FALLBACK=llama-3.3-70b-versatile # Complex legal reasoning
GROQ_MODEL_WHISPER=whisper-large-v3-turbo # Speech-to-text
# Ollama (local fallback, used when LLM_MODE=local)
OLLAMA_BASE_URL=http://ollama:11434
OLLAMA_MODEL=mistral:7b-instruct
# ChromaDB
CHROMA_HOST=localhost
CHROMA_PORT=8001
# RAG Ingestion
RAG_ALLOWED_DOMAINS=[]
RAG_STRIP_PROMPT_INJECTION=true
RAG_REDACT_PII=false
# Sentry (optional)
SENTRY_DSN=
SENTRY_TRACES_SAMPLE_RATE=1.0
SENTRY_ENVIRONMENT=development
# Evidence Storage
EVIDENCE_STORAGE_PATH=./storage/evidence
EVIDENCE_MAX_FILE_SIZE_MB=50Important
Never commit your .env file. It is already listed in .gitignore.
Tip
Get a free Groq API key at console.groq.com. The free tier supports up to 14,400 requests/day.
VITE_API_BASE_URL=http://localhost:8000/api/v1| Service | Image | Host Port | Container Port | Purpose |
|---|---|---|---|---|
db |
postgres:15-alpine | 5433 | 5432 | Main database |
redis |
redis:7-alpine | 6379 | 6379 | Session cache |
chromadb |
chromadb/chroma:latest | 8001 | 8000 | Vector store |
Place legal text files in backend/corpus/:
corpus/
βββ bns_2023/ # Bharatiya Nyaya Sanhita 2023 (replaces IPC)
βββ it_act_2000/ # Information Technology Act 2000
βββ pocso/ # POCSO Act
Ingest via admin API:
curl -X POST http://localhost:8000/api/v1/legal/corpus/ingest \
-H "Authorization: Bearer <admin_jwt>" \
-H "Content-Type: application/json"Contributions are welcome! Here's how to get involved:
- Fork the repository
- Create a feature branch:
git checkout -b feat/your-feature - Commit your changes:
git commit -m "feat: add your feature" - Push to your branch:
git push origin feat/your-feature - Open a Pull Request
Note
Please keep PRs focused β one feature or fix per PR makes review much easier.
# Backend dev (with hot reload)
cd backend && source venv/bin/activate
uvicorn app.server:app --host 127.0.0.1 --port 8000 --reload
# Frontend dev (with HMR)
cd frontend && npm run dev -- --host- Backend: Clean architecture β routes β controllers β services β repositories. Routes contain zero business logic.
- Frontend: Components in
/components, API calls in/services/api.js, state in/store/. - Models: Async SQLAlchemy 2.0 with
async defandawaitthroughout. - Config: All settings loaded from environment via Pydantic
BaseSettings. Never useos.environdirectly. - Audit: All critical actions logged to the immutable
audit_logstable.
Last updated: July 2026
Empowering Indian Law Enforcement with AI, RAG & BNS 2023
