gokulthiyagarajan/neural-justice-ksp-datathon

Purpose and Deployable Entry Points

Neural Justice is a Karnataka State Police crime-intelligence platform: FIR/case operations, role-scoped dashboards, geospatial and network analysis, reporting, and AI-assisted investigation. The React SPA starts at frontend/src/main.tsx and routes from frontend/src/App.tsx. The FastAPI service starts at backend/api/main.py; a separate Zoho Catalyst serverless handler exists at functions/neural-justice-backend/main.py.

Client Application and Role Boundaries

The TypeScript/React client presents dedicated CP, SP, PI, PSI, and PC workflows, with role-specific dashboards selected through frontend/src/pages/dashboards/DashboardRouter.tsx. Authentication state and login/MFA flow are client-side concerns in frontend/src/auth/LoginFlow.tsx and frontend/src/store/authStore.ts. Shared application shell, navigation, and jurisdiction-aware presentation sit in frontend/src/components/Layout/AppLayout.tsx and frontend/src/config/navConfig.ts.

API Surface and Operational Domains

FastAPI route modules split operational APIs by domain: cases/FIR-adjacent operations, dashboard data, stations, notifications, patrol, profiles, crime patterns, and CP-specific views. The API composition boundary is backend/api/main.py; representative domain endpoints are backend/api/routes/cases.py, backend/api/routes/dashboard.py, and backend/api/routes/cp.py. Client requests are isolated behind API clients such as frontend/src/api/client.ts, frontend/src/api/firs.ts, and frontend/src/api/copilot.ts.

AI Copilot: Request-to-Answer Pipeline

There are two connected AI implementations. The API copilot pipeline accepts/authenticates requests, detects intent, retrieves knowledge/datastore context, executes queries, and formats responses through backend/api/copilot/chat_pipeline.py, backend/api/copilot/intent.py, and backend/api/copilot/executor.py. Its HTTP boundary is backend/api/routes/copilot.py. The client interaction model—dock/panel, request lifecycle, and persisted UI state—is in frontend/src/copilot/CopilotDock.tsx, frontend/src/copilot/hooks/useCopilot.ts, and frontend/src/store/useCopilotStore.ts.

Multi-Stage Reasoning and Model Providers

A separate evidence-oriented reasoning pipeline explicitly progresses from generation to critical review, deep reasoning, consistency checking, and final assembly. Orchestration and routing are in backend/pipeline/orchestrator.py and backend/pipeline/router.py; stages are represented by backend/pipeline/stage_1_generation.py, backend/pipeline/stage_2_critical_review.py, backend/pipeline/stage_3_deep_reasoning.py, backend/pipeline/stage_4_consistency.py, and backend/pipeline/final_engine.py. Provider abstraction and QuickML integration are bounded by backend/ai/providers/base.py, backend/ai/providers/quickml.py, and backend/quickml/service.py; caching/evidence verification prevent repeated or unsupported output via backend/pipeline/response_cache.py and backend/pipeline/evidence_verifier.py.

Intelligence Visualization and Data Inputs

The SPA renders FIR operations, maps, hotspots, patrol context, and criminal networks. Major visualization boundaries are frontend/src/pages/GeoCommandPage.tsx, frontend/src/components/geo/MapProvider.tsx, and frontend/src/components/NetworkGraph/CytoscapeCanvas.tsx. Source data is supplied as SQLite databases in backend/ksp_demo.db and neural_justice.db, plus raw FIR CSVs under sample dataset's/datasets/Police_FIR_Dataset_CSVs/csv/; ingestion/seeding scripts are import_data.py and scripts/seed_full_db.py.

Runtime and Infrastructure

Local runtime is Node/Vite plus Python 3.11/FastAPI, typically using SQLite and optionally PostgreSQL. Production targets Zoho Catalyst, configured by .catalystrc and catalyst.json, with the static frontend and serverless function deployment model. Declared external integrations include Catalyst Data Store/NoSQL, QuickML, Zia OCR/Speech/Translation, SmartBrowz, push/signals, and OpenStreetMap-backed MapLibre/Leaflet maps. Authentication/security boundaries rely on JWT, TOTP, RBAC and jurisdictional access as reflected by backend/api/copilot/auth.py and the client login flow.