How anshdarji/nyaay-ai works
1. Overall shape
NYAAY AI is a two-tier product: a React/Vite frontend and a FastAPI backend. The backend is where nearly all business logic lives; the frontend is primarily a UI shell plus API client.
2. Frontend boundary
The React app in FRONTEND/src is organized by feature area: landing/dashboard, legal reasoning, drafting, Know Your Kanoon, and upload-chat. Shared UI lives under components/common, while feature-specific renderers and workflows live under components/chat, components/drafting, components/kanoon, components/reasoning, and components/uploadChat.
3. Backend entry and API layer
BACKEND/app/main.py boots the FastAPI application and mounts route groups from app/routes. The API surface is split by capability: auth, chat, drafting, kanoon, reasoning, upload_chat, and admin. These routes are thin entry points that delegate to service classes.
4. Service boundary
The app/services layer is the main business-logic boundary between HTTP and the domain subsystems. It contains dedicated services for auth, document handling, Kanoon/legal query handling, reasoning, title generation, and upload-chat. This is the layer most likely to orchestrate database access, AI calls, and retrieval.
5. AI and drafting subsystem
The app/ai package contains the LLM-facing orchestration logic: prompt building, guardrails, domain classification, sanity checking, validation, and a drafting orchestrator. This subsystem is separate from document rendering, which is intentionally deterministic. The model produces structured content, not final formatting.
6. Deterministic legal drafting pipeline
Drafting is template-driven. The templates under app/templates/* each include instructions, reference material, and a JSON schema. The backend validates generated output against schema/Pydantic models, then passes it to utilities in app/utils/document_generators.py and document_ast.py to produce PDF/DOCX output with controlled formatting.
7. RAG / legal knowledge subsystem
Legal question answering is backed by the app/knowledge package. It combines chunking, embeddings, BM25, a vector store, and a hybrid retriever. This is the retrieval layer used by the reasoning and Kanoon flows to ground answers in Indian legal corpora.
8. Corpus and ingestion pipeline
The repository separates source legal material from processed knowledge. Raw and processed corpus artifacts live under BACKEND/corpus, BACKEND/data/raw, and BACKEND/data/corpus, with manifests in BACKEND/data/corpus_manifest*.json. The ingestion pipeline in app/ingestion and app/acquisition handles parsing, normalization, validation, metadata extraction, and markdown generation before material is indexed into the knowledge system.
9. Document upload and analysis flow
Uploaded files are stored under BACKEND/uploads. The upload_chat route and service pair work with document parsing/validation modules to extract text from PDFs/DOCX, then use AI/document-sanity checks and chat-style responses. This is a separate flow from legal drafting: it analyzes user-provided documents rather than generating new ones.
10. Authentication and request protection
Authentication is Firebase-based on the frontend and backend. The frontend uses Firebase Auth, while the backend verifies tokens via Firebase Admin in app/core/firebase.py and middleware in app/middleware/auth.py. The backend also includes rate limiting, logging, and metrics under app/core, indicating production-oriented request controls.
11. Data persistence
Structured application state is stored in SQLite via SQLAlchemy (app/database and app/models). The models include users, chats, documents, and reasoning-related entities. This persistent layer supports history, auditability, and recovered context for the AI workflows.
12. External dependencies and runtime
The backend depends materially on the Google Gemini API for generation, Firebase for identity, and ChromaDB/BM25-style retrieval for grounding. The system is containerized with Docker, uses Nginx for serving/proxying the frontend in deployment, and is wired for local or compose-based startup.
13. Operational and quality tooling
The repo includes substantial non-production tooling: tests/ for unit/e2e/load coverage, devtools/ for smoke tests and inspection, scripts/ for corpus ingestion and benchmarking, and eval/ for benchmark runs and reports. These are part of the architecture because they validate the ingestion, retrieval, drafting, and API behavior end to end.
14. Key architectural boundary to diagram
The most important separation is between: user-facing UI, API/service orchestration, AI/retrieval subsystems, and deterministic document rendering/storage. The AI is used for content and reasoning; formatting, persistence, retrieval indexing, and authentication are all controlled by backend code and supporting infrastructure.
Main entry points: routes Route layer · services Service layer · App.jsx App shell · ai AI orchestration
Components 19
Frontend
React/Vite UI shell and feature renderers
- App shell · Top-level client app and page routing
FRONTEND/src/App.jsx - Shared UI · Reusable UI primitives and chrome
FRONTEND/src/components/common - Feature UIs · Chat, drafting, kanoon, reasoning, and upload-chat renderers
FRONTEND/src/components - API clients · Browser-side service layer and Firebase auth config
FRONTEND/src/services
Backend
FastAPI app, services, AI, retrieval, and persistence
- FastAPI app · Application bootstrap and route mounting
BACKEND/app/main.py - Route layer · Auth, chat, drafting, kanoon, reasoning, upload, and admin endpoints
BACKEND/app/routes - Service layer · Orchestrates auth, documents, kanoon, reasoning, titles, and upload-chat
BACKEND/app/services - AI orchestration · Prompting, guardrails, validation, domain classification, and drafting orchestration
BACKEND/app/ai - RAG layer · Chunking, embeddings, BM25, vector store, and hybrid retrieval
BACKEND/app/knowledge - Ingestion pipeline · Parsing, normalization, metadata extraction, markdown generation, and validation
BACKEND/app/ingestion - Acquisition · Download, parse, metadata, update checks, and source validation
BACKEND/app/acquisition - Draft templates · Template instructions, references, and JSON schemas for legal documents
BACKEND/app/templates - Doc renderer · Deterministic AST and PDF/DOCX generation utilities
BACKEND/app/utils/document_generators.py - Core infra · Config, Firebase verification, logging, rate limiting, and metrics
BACKEND/app/core - Persistence · Database connection and domain models for users, chats, documents, and reasoning
BACKEND/app/database
Corpus & Storage
Source legal material, processed corpus, and uploads
- Legal corpus · Raw and processed Indian legal texts and judgments
BACKEND/corpus - Uploads & DB · Uploaded files and local SQLite database file
BACKEND/uploads
Ops & Tooling
Deployment, evaluation, and validation utilities
- Tooling · Tests, devtools, benchmark scripts, and evaluation reports
BACKEND/tests - Deploy stack · Docker, Nginx, and compose-based runtime setup
docker-compose.yml
Connections 24
- App shell → Shared UI: uses · App composes shared UI primitives
- App shell → Feature UIs: renders · App routes to feature-specific screens
- App shell → API clients: calls · UI delegates network and auth operations to client services
- API clients → Route layer: API calls · Browser services talk to backend endpoints
- FastAPI app → Route layer: mounts · FastAPI bootstraps route groups
- Route layer → Service layer: delegates · Thin HTTP layer forwards work to services
- Service layer → AI orchestration: orchestrates · Services invoke AI for reasoning, drafting, and validation
- Service layer → RAG layer: retrieves · Kanoon and reasoning flows ground responses in legal corpora
- Service layer → Persistence: persists · Services store users, chats, documents, and reasoning state
- Service layer → Doc renderer: generates docs · Drafting service converts validated structure into PDF/DOCX
- AI orchestration → Draft templates: fills · LLM output is shaped by template instructions and schemas
- AI orchestration → Doc renderer: hand-off · AI produces structured content before deterministic rendering
- RAG layer → Legal corpus: indexes · Retriever is grounded in corpus and processed legal texts
- Ingestion pipeline → Legal corpus: builds · Ingestion turns raw legal material into indexed corpus assets
- Acquisition → Ingestion pipeline: feeds · Acquisition supplies parsed and validated source material
- Core infra → FastAPI app: supports · Core infra underpins app runtime and security
- Core infra → Route layer: protects · Auth, rate limiting, logging, and metrics wrap requests
- Persistence → Uploads & DB: stores · SQLite persistence lives alongside runtime uploads
- Route layer → RAG layer: queries · Reasoning and Kanoon endpoints use retrieval services
- Route layer → Doc renderer: exports · Drafting endpoints trigger deterministic document generation
- Tooling → Ingestion pipeline: validates · Scripts and tests exercise ingestion and corpus quality
- Tooling → AI orchestration: benchmarks · Evaluation tooling checks orchestration and model behavior
- Deploy stack → App shell: serves · Nginx/container stack serves the frontend
- Deploy stack → FastAPI app: runs · Container stack runs the API backend