# aryandhole594-art/nyayasetu architecture

> Architecture diagram of the GitHub repository aryandhole594-art/nyayasetu, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/aryandhole594-art/nyayasetu
- Repository: https://github.com/aryandhole594-art/nyayasetu

## Overview

1. NyayaSetu is a multi-module legal-assistant monorepo centered on Indian constitutional law. The core architecture is a Flask backend that exposes legal Q&A and tool APIs, a React frontend that consumes them, and several adjacent specialty modules for drafting, precedent prediction, and rights/compliance logic.

2. The primary runtime is `backend/app.py` (with `app_remote.py` for an alternate deployment path). This Flask server owns the main HTTP surface: `/api/chat`, the advanced reasoning endpoints, and document-intelligence endpoints. The routes are split into blueprints under `backend/routes`, which keeps the API boundary clean by feature area.

3. The main answer-generation path is retrieval-augmented. Queries flow through `backend/rag_engine.py` and `backend/utils/retriever.py`, which combine BM25, TF-IDF, and title boosting over the constitutional text and case corpus. Retrieved context is then passed to an LLM via `backend/utils/llm_client.py`, with `backend/utils/hallucination_guard.py` and `backend/utils/explainability.py` adding safety and traceability.

4. The backend’s “advanced legal tools” are implemented as modular feature services in `backend/features`. These include amendment tracking, article comparison, fairness checking, layman-to-legal translation, rights-card generation, and scenario simulation. Each tool is exposed through its own route blueprint and returns structured output, not just free-form text.

5. A key architectural boundary is the standardized response schema described in the README. Advanced endpoints return status, feature name, structured data, confidence, warnings, and explainability metadata such as retrieved chunks, sources, and reasoning steps. That makes downstream UI rendering and auditability consistent across tools.

6. Document intelligence is a separate pipeline under `backend/document_intelligence.py` and `backend/legal_doc_intel.py`. It supports file upload, OCR/text extraction, contract risk analysis, and court-notice decoding. The pipeline merges extracted content back into the legal corpus and uses grounding against constitutional/legal sources to reduce purely heuristic judgments.

7. The repository also contains a standalone `precedent_module`, which is a separate Flask app for precedent-based case prediction. Its `index_cases.py`, `predictor.py`, and `evaluator.py` suggest an isolated index-build-and-predict workflow, distinct from the main chatbot RAG flow. This module is likely meant to be deployed independently or integrated later.

8. `drafting_module` is another self-contained service focused on legal document generation. It has its own app, ingestion/processing/sanitization stages, a template library, and generated output directories. This is a separate boundary from the conversational assistant: it turns structured inputs into document templates rather than answering legal questions.

9. `rights_module` appears to be a rule/compliance subsystem. It includes a situation classifier, corpus loader, rights handler, and compliance checker, indicating a deterministic or semi-deterministic rights-assessment path that complements the LLM-based assistant. Architecturally, it functions like a domain rules engine for specific legal situations.

10. The frontend is a React app in `frontend/` that serves the user-facing product experience. It includes pages and components for legal query handling, judgement prediction, drafting, and an “AI legal tools” experience. The frontend talks to the Flask backend over HTTP and is configured for local development on port 3000 against backend port 5555.

11. The floating NyayaSetu bot widget is a notable cross-cutting UI subsystem. Its JavaScript/CSS assets exist both under `frontend/public/static/bot` and `backend/static/bot`, which indicates the widget can be served from either the React app or Flask static hosting. The bot has two modes: Legal Assistant mode hits `/api/chat`, while Site Guide mode answers from a static site knowledge base.

12. The knowledge and corpus layer is file-based and domain-specific. `backend/constitution.txt`, `backend/static/constitution.pdf`, and `backend/data/*.json` provide constitutional and mapping data, while `case_corpus/` contains a large collection of topic-labeled case texts used for retrieval and benchmarking. The `corpus/` directory holds law PDFs used for ingestion/sample generation.

13. A few endpoints are intentionally stubbed and act as future integration points: document analyzer, petition draft, landmark cases, bail eligibility, and legal timeline return 501 until their retrieve→generate flow is implemented. This makes the current architecture a hybrid of production-ready tools and explicit extension seams.

14. Testing is focused on core behavioral boundaries rather than broad UI coverage. The `tests/` directory validates bot intent classification, fairness checking, hallucination guarding, and retrieval quality, which matches the system’s main risk areas: routing, grounding, and answer reliability.

15. Operationally, the repo is designed for local-first deployment with optional external LLMs. The backend can use Ollama locally or Gemini as a fallback, and the README notes Tesseract for OCR. Those external dependencies matter because they affect the inference boundary, latency, and document-intelligence capabilities more than the basic app structure.

Main entry points: [`backend/routes`](https://github.com/aryandhole594-art/nyayasetu/tree/main/backend/routes) (API routes), [`backend/rag_engine.py`](https://github.com/aryandhole594-art/nyayasetu/blob/main/backend/rag_engine.py) (RAG engine), [`backend/utils/retriever.py`](https://github.com/aryandhole594-art/nyayasetu/blob/main/backend/utils/retriever.py) (Retriever), [`backend/constitution.txt`](https://github.com/aryandhole594-art/nyayasetu/blob/main/backend/constitution.txt) (Constitution)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_backend["Backend"]
  node_backend_app["Flask app<br/>api server<br/>[app.py]"]
  node_backend_remote["Remote app<br/>deploy variant<br/>[app_remote.py]"]
  node_backend_routes["API routes<br/>blueprints"]
  node_backend_rag["RAG engine<br/>answer pipeline<br/>[rag_engine.py]"]
  node_backend_retriever["Retriever<br/>search ranker<br/>[retriever.py]"]
  node_backend_llm["LLM client<br/>model adapter<br/>[llm_client.py]"]
  node_backend_safety["Safety layer<br/>guardrails"]
  node_backend_features["Legal tools<br/>feature services"]
  node_backend_docintel["Doc intel<br/>document pipeline"]
  node_backend_legaldoc["Legal intel<br/>doc analysis<br/>[legal_doc_intel.py]"]
end

subgraph group_frontend["Frontend"]
  node_frontend_app["React app<br/>ui shell<br/>[App.js]"]
  node_frontend_tools["Tool UI<br/>feature pages"]
  node_frontend_bot["Bot widget<br/>chat widget<br/>[nyayasetu_bot.js]"]
end

subgraph group_modules["Specialty Modules"]
  node_precedent_app["Precedent app<br/>case predictor<br/>[app.py]"]
  node_precedent_index["Case index<br/>index builder<br/>[index_cases.py]"]
  node_precedent_predict["Predictor<br/>prediction engine<br/>[predictor.py]"]
  node_drafting_app["Drafting app<br/>doc generator<br/>[app.py]"]
  node_drafting_pipeline["Draft pipeline<br/>ingest-process<br/>[processor.py]"]
  node_rights_module["Rights engine<br/>rules engine<br/>[rights_handler.py]"]
end

subgraph group_knowledge["Knowledge Base"]
  node_constitution["Constitution<br/>primary corpus<br/>[constitution.txt]"]
  node_case_corpus["Case corpus<br/>retrieval corpus"]
end

node_backend_app -->|"registers"| node_backend_routes
node_backend_remote -->|"registers"| node_backend_routes
node_backend_routes -->|"chat"| node_backend_rag
node_backend_routes -->|"tools"| node_backend_features
node_backend_routes -->|"document APIs"| node_backend_docintel
node_backend_rag -->|"retrieves"| node_backend_retriever
node_backend_rag -->|"generates"| node_backend_llm
node_backend_rag -->|"guards"| node_backend_safety
node_backend_retriever -->|"grounds on"| node_constitution
node_backend_retriever -->|"searches"| node_case_corpus
node_backend_docintel -->|"analyzes"| node_backend_legaldoc
node_backend_features -->|"served by"| node_backend_routes
node_frontend_app -->|"HTTP API"| node_backend_app
node_frontend_tools -->|"renders in"| node_frontend_app
node_frontend_bot -->|"chat mode"| node_backend_routes
node_frontend_bot -->|"site guide"| node_constitution
node_precedent_app -->|"indexes"| node_precedent_index
node_precedent_app -->|"predicts"| node_precedent_predict
node_drafting_app -->|"processes"| node_drafting_pipeline
node_rights_module -->|"interprets"| node_constitution

click node_backend_app "https://github.com/aryandhole594-art/nyayasetu/blob/main/backend/app.py"
click node_backend_remote "https://github.com/aryandhole594-art/nyayasetu/blob/main/backend/app_remote.py"
click node_backend_routes "https://github.com/aryandhole594-art/nyayasetu/tree/main/backend/routes"
click node_backend_rag "https://github.com/aryandhole594-art/nyayasetu/blob/main/backend/rag_engine.py"
click node_backend_retriever "https://github.com/aryandhole594-art/nyayasetu/blob/main/backend/utils/retriever.py"
click node_backend_llm "https://github.com/aryandhole594-art/nyayasetu/blob/main/backend/utils/llm_client.py"
click node_backend_safety "https://github.com/aryandhole594-art/nyayasetu/blob/main/backend/utils/hallucination_guard.py"
click node_backend_features "https://github.com/aryandhole594-art/nyayasetu/tree/main/backend/features"
click node_backend_docintel "https://github.com/aryandhole594-art/nyayasetu/blob/main/backend/document_intelligence.py"
click node_backend_legaldoc "https://github.com/aryandhole594-art/nyayasetu/blob/main/backend/legal_doc_intel.py"
click node_frontend_app "https://github.com/aryandhole594-art/nyayasetu/blob/main/frontend/src/App.js"
click node_frontend_tools "https://github.com/aryandhole594-art/nyayasetu/tree/main/frontend/src/components"
click node_frontend_bot "https://github.com/aryandhole594-art/nyayasetu/blob/main/frontend/public/static/bot/nyayasetu_bot.js"
click node_precedent_app "https://github.com/aryandhole594-art/nyayasetu/blob/main/precedent_module/app.py"
click node_precedent_index "https://github.com/aryandhole594-art/nyayasetu/blob/main/precedent_module/index_cases.py"
click node_precedent_predict "https://github.com/aryandhole594-art/nyayasetu/blob/main/precedent_module/predictor.py"
click node_drafting_app "https://github.com/aryandhole594-art/nyayasetu/blob/main/drafting_module/app.py"
click node_drafting_pipeline "https://github.com/aryandhole594-art/nyayasetu/blob/main/drafting_module/processor.py"
click node_rights_module "https://github.com/aryandhole594-art/nyayasetu/blob/main/rights_module/rights_handler.py"
click node_constitution "https://github.com/aryandhole594-art/nyayasetu/blob/main/backend/constitution.txt"
click node_case_corpus "https://github.com/aryandhole594-art/nyayasetu/tree/main/case_corpus"

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_backend_app,node_backend_remote,node_backend_routes,node_backend_rag,node_backend_retriever,node_backend_llm,node_backend_safety,node_backend_features,node_backend_docintel,node_backend_legaldoc toneBlue
class node_frontend_app,node_frontend_tools,node_frontend_bot toneAmber
class node_precedent_app,node_precedent_index,node_precedent_predict,node_drafting_app,node_drafting_pipeline,node_rights_module toneMint
class node_constitution,node_case_corpus toneRose
```

## Components

### Backend

Flask API, retrieval, and legal tools

- [Flask app](https://github.com/aryandhole594-art/nyayasetu/blob/main/backend/app.py): api server · Main Flask entrypoint for HTTP APIs and deployment wiring · `backend/app.py`
- [Remote app](https://github.com/aryandhole594-art/nyayasetu/blob/main/backend/app_remote.py): deploy variant · Alternate Flask deployment path · `backend/app_remote.py`
- [API routes](https://github.com/aryandhole594-art/nyayasetu/tree/main/backend/routes): blueprints · Feature-split route layer for chat, tools, and stubs · `backend/routes`
- [RAG engine](https://github.com/aryandhole594-art/nyayasetu/blob/main/backend/rag_engine.py): answer pipeline · Coordinates retrieval-augmented legal answering · `backend/rag_engine.py`
- [Retriever](https://github.com/aryandhole594-art/nyayasetu/blob/main/backend/utils/retriever.py): search ranker · BM25, TF-IDF, and title-boost retrieval over legal sources · `backend/utils/retriever.py`
- [LLM client](https://github.com/aryandhole594-art/nyayasetu/blob/main/backend/utils/llm_client.py): model adapter · LLM access layer for local or external generation · `backend/utils/llm_client.py`
- [Safety layer](https://github.com/aryandhole594-art/nyayasetu/blob/main/backend/utils/hallucination_guard.py): guardrails · Hallucination checks and response explainability · `backend/utils/hallucination_guard.py`
- [Legal tools](https://github.com/aryandhole594-art/nyayasetu/tree/main/backend/features): feature services · Modular advanced legal tools exposed through dedicated endpoints · `backend/features`
- [Doc intel](https://github.com/aryandhole594-art/nyayasetu/blob/main/backend/document_intelligence.py): document pipeline · Upload, OCR, extraction, and grounded legal document analysis · `backend/document_intelligence.py`
- [Legal intel](https://github.com/aryandhole594-art/nyayasetu/blob/main/backend/legal_doc_intel.py): doc analysis · Contract risk and notice decoding logic · `backend/legal_doc_intel.py`

### Frontend

React UI and bot widget

- [React app](https://github.com/aryandhole594-art/nyayasetu/blob/main/frontend/src/App.js): ui shell · Main browser application for queries, tools, and prediction flows · `frontend/src/App.js`
- [Tool UI](https://github.com/aryandhole594-art/nyayasetu/tree/main/frontend/src/components): feature pages · UI for legal query, drafting, prediction, and advanced tools · `frontend/src/components`
- [Bot widget](https://github.com/aryandhole594-art/nyayasetu/blob/main/frontend/public/static/bot/nyayasetu_bot.js): chat widget · Floating assistant with legal-assistant and site-guide modes · `frontend/public/static/bot/nyayasetu_bot.js`

### Specialty Modules

Standalone legal services

- [Precedent app](https://github.com/aryandhole594-art/nyayasetu/blob/main/precedent_module/app.py): case predictor · Standalone Flask service for precedent-based prediction · `precedent_module/app.py`
- [Case index](https://github.com/aryandhole594-art/nyayasetu/blob/main/precedent_module/index_cases.py): index builder · Builds case index and vectors for precedent lookup · `precedent_module/index_cases.py`
- [Predictor](https://github.com/aryandhole594-art/nyayasetu/blob/main/precedent_module/predictor.py): prediction engine · Generates precedent-based case outcome predictions · `precedent_module/predictor.py`
- [Drafting app](https://github.com/aryandhole594-art/nyayasetu/blob/main/drafting_module/app.py): doc generator · Standalone legal document generation service · `drafting_module/app.py`
- [Draft pipeline](https://github.com/aryandhole594-art/nyayasetu/blob/main/drafting_module/processor.py): ingest-process · Ingestion, processing, and sanitization for template filling · `drafting_module/processor.py`
- [Rights engine](https://github.com/aryandhole594-art/nyayasetu/blob/main/rights_module/rights_handler.py): rules engine · Situation classification and compliance checks for rights analysis · `rights_module/rights_handler.py`

### Knowledge Base

Constitution, cases, and PDFs

- [Constitution](https://github.com/aryandhole594-art/nyayasetu/blob/main/backend/constitution.txt): primary corpus · Core constitutional text used across retrieval and tools · `backend/constitution.txt`
- [Case corpus](https://github.com/aryandhole594-art/nyayasetu/tree/main/case_corpus): retrieval corpus · Topic-labeled case texts used for retrieval and benchmarking · `case_corpus`

## Connections

- Flask app → API routes: registers · Main app mounts feature blueprints
- Remote app → API routes: registers · Alternate deployment path uses same API surface
- API routes → RAG engine: chat · Chat endpoint delegates to retrieval-augmented answering
- API routes → Legal tools: tools · Advanced endpoints dispatch to feature services
- API routes → Doc intel: document APIs · Document intelligence routes call analysis pipeline
- RAG engine → Retriever: retrieves · Pulls relevant constitutional and case context
- RAG engine → LLM client: generates · Sends grounded context to the model client
- RAG engine → Safety layer: guards · Applies hallucination checks and traceability
- Retriever → Constitution: grounds on · Uses constitutional text as a primary source
- Retriever → Case corpus: searches · Ranks case texts for supporting context
- Doc intel → Legal intel: analyzes · Document pipeline delegates legal-specific interpretation
- Legal tools → API routes: served by · Tool services are exposed through blueprints
- React app → Flask app: HTTP API · React UI consumes Flask backend endpoints
- Tool UI → React app: renders in · Tool pages live within the main React application
- Bot widget → API routes: chat mode · Legal Assistant mode calls the chat API
- Bot widget → Constitution: site guide · Site Guide mode uses static knowledge content
- Precedent app → Case index: indexes · Service builds precedent search structures
- Precedent app → Predictor: predicts · Prediction flow uses indexed cases and model logic
- Drafting app → Draft pipeline: processes · Drafting service runs ingestion and sanitization pipeline
- Rights engine → Constitution: interprets · Rights checks are grounded in legal source material
