# anshdarji/nyaay-ai architecture

> Architecture diagram of the GitHub repository anshdarji/nyaay-ai, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/anshdarji/nyaay-ai
- Repository: https://github.com/anshdarji/nyaay-ai

## Overview

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: [`BACKEND/app/routes`](https://github.com/anshdarji/nyaay-ai/tree/main/BACKEND/app/routes) (Route layer), [`BACKEND/app/services`](https://github.com/anshdarji/nyaay-ai/tree/main/BACKEND/app/services) (Service layer), [`FRONTEND/src/App.jsx`](https://github.com/anshdarji/nyaay-ai/blob/main/FRONTEND/src/App.jsx) (App shell), [`BACKEND/app/ai`](https://github.com/anshdarji/nyaay-ai/tree/main/BACKEND/app/ai) (AI orchestration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_frontend_app["App shell<br/>React/Vite<br/>[App.jsx]"]
  node_frontend_common["Shared UI<br/>components"]
  node_frontend_features["Feature UIs<br/>feature components"]
  node_frontend_api["API clients<br/>services"]
end

subgraph group_backend["Backend"]
  node_backend_main["FastAPI app<br/>entrypoint<br/>[main.py]"]
  node_backend_routes["Route layer<br/>HTTP routes"]
  node_backend_services["Service layer<br/>business services"]
  node_backend_ai["AI orchestration<br/>LLM pipeline"]
  node_backend_knowledge["RAG layer<br/>retrieval"]
  node_backend_ingestion["Ingestion pipeline<br/>corpus pipeline"]
  node_backend_acquisition["Acquisition<br/>source ingestion"]
  node_backend_templates["Draft templates<br/>schemas"]
  node_backend_docgen["Doc renderer<br/>document generation"]
  node_backend_core["Core infra<br/>platform services"]
  node_backend_db[("Persistence<br/>SQLAlchemy/SQLite")]
end

subgraph group_data["Corpus & Storage"]
  node_data_corpus["Legal corpus<br/>source data"]
  node_data_storage[("Uploads & DB<br/>runtime storage")]
end

subgraph group_ops["Ops & Tooling"]
  node_ops_tooling["Tooling<br/>tests/scripts/eval"]
  node_ops_deploy["Deploy stack<br/>container/runtime<br/>[docker-compose.yml]"]
end

node_frontend_app -->|"uses"| node_frontend_common
node_frontend_app -->|"renders"| node_frontend_features
node_frontend_app -->|"calls"| node_frontend_api
node_frontend_api -->|"API calls"| node_backend_routes
node_backend_main -->|"mounts"| node_backend_routes
node_backend_routes -->|"delegates"| node_backend_services
node_backend_services -->|"orchestrates"| node_backend_ai
node_backend_services -->|"retrieves"| node_backend_knowledge
node_backend_services -->|"persists"| node_backend_db
node_backend_services -->|"generates docs"| node_backend_docgen
node_backend_ai -->|"fills"| node_backend_templates
node_backend_ai -.->|"hand-off"| node_backend_docgen
node_backend_knowledge -->|"indexes"| node_data_corpus
node_backend_ingestion -->|"builds"| node_data_corpus
node_backend_acquisition -->|"feeds"| node_backend_ingestion
node_backend_core -->|"supports"| node_backend_main
node_backend_core -->|"protects"| node_backend_routes
node_backend_db -->|"stores"| node_data_storage
node_backend_routes -->|"queries"| node_backend_knowledge
node_backend_routes -->|"exports"| node_backend_docgen
node_ops_tooling -.->|"validates"| node_backend_ingestion
node_ops_tooling -.->|"benchmarks"| node_backend_ai
node_ops_deploy -->|"serves"| node_frontend_app
node_ops_deploy -->|"runs"| node_backend_main

click node_frontend_app "https://github.com/anshdarji/nyaay-ai/blob/main/FRONTEND/src/App.jsx"
click node_frontend_common "https://github.com/anshdarji/nyaay-ai/tree/main/FRONTEND/src/components/common"
click node_frontend_features "https://github.com/anshdarji/nyaay-ai/tree/main/FRONTEND/src/components"
click node_frontend_api "https://github.com/anshdarji/nyaay-ai/tree/main/FRONTEND/src/services"
click node_backend_main "https://github.com/anshdarji/nyaay-ai/blob/main/BACKEND/app/main.py"
click node_backend_routes "https://github.com/anshdarji/nyaay-ai/tree/main/BACKEND/app/routes"
click node_backend_services "https://github.com/anshdarji/nyaay-ai/tree/main/BACKEND/app/services"
click node_backend_ai "https://github.com/anshdarji/nyaay-ai/tree/main/BACKEND/app/ai"
click node_backend_knowledge "https://github.com/anshdarji/nyaay-ai/tree/main/BACKEND/app/knowledge"
click node_backend_ingestion "https://github.com/anshdarji/nyaay-ai/tree/main/BACKEND/app/ingestion"
click node_backend_acquisition "https://github.com/anshdarji/nyaay-ai/tree/main/BACKEND/app/acquisition"
click node_backend_templates "https://github.com/anshdarji/nyaay-ai/tree/main/BACKEND/app/templates"
click node_backend_docgen "https://github.com/anshdarji/nyaay-ai/blob/main/BACKEND/app/utils/document_generators.py"
click node_backend_core "https://github.com/anshdarji/nyaay-ai/tree/main/BACKEND/app/core"
click node_backend_db "https://github.com/anshdarji/nyaay-ai/tree/main/BACKEND/app/database"
click node_data_corpus "https://github.com/anshdarji/nyaay-ai/tree/main/BACKEND/corpus"
click node_data_storage "https://github.com/anshdarji/nyaay-ai/tree/main/BACKEND/uploads"
click node_ops_tooling "https://github.com/anshdarji/nyaay-ai/tree/main/BACKEND/tests"
click node_ops_deploy "https://github.com/anshdarji/nyaay-ai/blob/main/docker-compose.yml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_frontend_app,node_frontend_common,node_frontend_features,node_frontend_api toneBlue
class node_backend_main,node_backend_routes,node_backend_services,node_backend_ai,node_backend_knowledge,node_backend_ingestion,node_backend_acquisition,node_backend_templates,node_backend_docgen,node_backend_core,node_backend_db toneAmber
class node_data_corpus,node_data_storage toneMint
class node_ops_tooling,node_ops_deploy toneRose
```

## Components

### Frontend

React/Vite UI shell and feature renderers

- [App shell](https://github.com/anshdarji/nyaay-ai/blob/main/FRONTEND/src/App.jsx): React/Vite · Top-level client app and page routing · `FRONTEND/src/App.jsx`
- [Shared UI](https://github.com/anshdarji/nyaay-ai/tree/main/FRONTEND/src/components/common): components · Reusable UI primitives and chrome · `FRONTEND/src/components/common`
- [Feature UIs](https://github.com/anshdarji/nyaay-ai/tree/main/FRONTEND/src/components): feature components · Chat, drafting, kanoon, reasoning, and upload-chat renderers · `FRONTEND/src/components`
- [API clients](https://github.com/anshdarji/nyaay-ai/tree/main/FRONTEND/src/services): services · Browser-side service layer and Firebase auth config · `FRONTEND/src/services`

### Backend

FastAPI app, services, AI, retrieval, and persistence

- [FastAPI app](https://github.com/anshdarji/nyaay-ai/blob/main/BACKEND/app/main.py): entrypoint · Application bootstrap and route mounting · `BACKEND/app/main.py`
- [Route layer](https://github.com/anshdarji/nyaay-ai/tree/main/BACKEND/app/routes): HTTP routes · Auth, chat, drafting, kanoon, reasoning, upload, and admin endpoints · `BACKEND/app/routes`
- [Service layer](https://github.com/anshdarji/nyaay-ai/tree/main/BACKEND/app/services): business services · Orchestrates auth, documents, kanoon, reasoning, titles, and upload-chat · `BACKEND/app/services`
- [AI orchestration](https://github.com/anshdarji/nyaay-ai/tree/main/BACKEND/app/ai): LLM pipeline · Prompting, guardrails, validation, domain classification, and drafting orchestration · `BACKEND/app/ai`
- [RAG layer](https://github.com/anshdarji/nyaay-ai/tree/main/BACKEND/app/knowledge): retrieval · Chunking, embeddings, BM25, vector store, and hybrid retrieval · `BACKEND/app/knowledge`
- [Ingestion pipeline](https://github.com/anshdarji/nyaay-ai/tree/main/BACKEND/app/ingestion): corpus pipeline · Parsing, normalization, metadata extraction, markdown generation, and validation · `BACKEND/app/ingestion`
- [Acquisition](https://github.com/anshdarji/nyaay-ai/tree/main/BACKEND/app/acquisition): source ingestion · Download, parse, metadata, update checks, and source validation · `BACKEND/app/acquisition`
- [Draft templates](https://github.com/anshdarji/nyaay-ai/tree/main/BACKEND/app/templates): schemas · Template instructions, references, and JSON schemas for legal documents · `BACKEND/app/templates`
- [Doc renderer](https://github.com/anshdarji/nyaay-ai/blob/main/BACKEND/app/utils/document_generators.py): document generation · Deterministic AST and PDF/DOCX generation utilities · `BACKEND/app/utils/document_generators.py`
- [Core infra](https://github.com/anshdarji/nyaay-ai/tree/main/BACKEND/app/core): platform services · Config, Firebase verification, logging, rate limiting, and metrics · `BACKEND/app/core`
- [Persistence](https://github.com/anshdarji/nyaay-ai/tree/main/BACKEND/app/database): SQLAlchemy/SQLite · 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](https://github.com/anshdarji/nyaay-ai/tree/main/BACKEND/corpus): source data · Raw and processed Indian legal texts and judgments · `BACKEND/corpus`
- [Uploads & DB](https://github.com/anshdarji/nyaay-ai/tree/main/BACKEND/uploads): runtime storage · Uploaded files and local SQLite database file · `BACKEND/uploads`

### Ops & Tooling

Deployment, evaluation, and validation utilities

- [Tooling](https://github.com/anshdarji/nyaay-ai/tree/main/BACKEND/tests): tests/scripts/eval · Tests, devtools, benchmark scripts, and evaluation reports · `BACKEND/tests`
- [Deploy stack](https://github.com/anshdarji/nyaay-ai/blob/main/docker-compose.yml): container/runtime · Docker, Nginx, and compose-based runtime setup · `docker-compose.yml`

## Connections

- 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
