# rk0297/legal-chatbot architecture

> Architecture diagram of the GitHub repository rk0297/legal-chatbot, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rk0297/legal-chatbot
- Repository: https://github.com/rk0297/legal-chatbot

## Overview

Kanoon is an Indian-law RAG assistant. Citizens, advocates, and researchers submit questions through the web UI or API; the API delegates consultation to RAG, which reformulates queries, retrieves and reranks legal context, applies emergency and disclaimer guardrails, and generates a response through Groq. Separate routes support direct search, document lookup, uploads, and evaluation. The README documents further ingestion and retrieval capabilities; sampled excerpts do not expose every route’s wiring, so only supported relationships are drawn.

Main entry points: [`server/api/routes.py`](https://github.com/rk0297/legal-chatbot/blob/main/server/api/routes.py) (API routes), [`server/services/rag_service.py`](https://github.com/rk0297/legal-chatbot/blob/main/server/services/rag_service.py) (RAG orchestration), [`server/evaluation/evaluator.py`](https://github.com/rk0297/legal-chatbot/blob/main/server/evaluation/evaluator.py) (RAG evaluator), [`server/services/groq_service.py`](https://github.com/rk0297/legal-chatbot/blob/main/server/services/groq_service.py) (Inference client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client"]
  node_ui["Web interface<br/>[index.html]"]
end

subgraph group_api["API"]
  node_main["App runtime<br/>[main.py]"]
  node_routes["API routes<br/>[routes.py]"]
  node_schemas["API schemas<br/>[schemas.py]"]
end

subgraph group_consult["Consultation"]
  node_rag["RAG orchestration<br/>[rag_service.py]"]
  node_selfquery["Query reformulation"]
  node_guardrails["Legal guardrails<br/>[guardrails.py]"]
  node_groqservice["Inference client<br/>[groq_service.py]"]
end

subgraph group_knowledge["Legal Knowledge"]
  node_hybrid["Hybrid retrieval<br/>[hybrid_search.py]"]
  node_vector[("Vector store<br/>[vector_store.py]")]
  node_dataset["Corpus loading<br/>[dataset_loader.py]"]
  node_parser["Document parsing<br/>[document_parser.py]"]
  node_chunker["Legal chunking<br/>[chunking.py]"]
end

subgraph group_quality["Evaluation"]
  node_eval["RAG evaluator<br/>[evaluator.py]"]
  node_metrics["IR metrics<br/>[metrics.py]"]
  node_judge["LLM judge<br/>[llm_judge.py]"]
end

node_user(("Legal user"))
node_groqcloud{{"Groq Cloud"}}

node_user -->|"asks question"| node_ui
node_ui -->|"sends requests"| node_routes
node_main -->|"mounts API"| node_routes
node_main -->|"serves UI"| node_ui
node_routes -->|"delegates chat"| node_rag
node_rag -->|"reformulates"| node_selfquery
node_rag -->|"retrieves context"| node_hybrid
node_rag -->|"checks distress"| node_guardrails
node_rag -->|"generates answer"| node_groqservice
node_selfquery -->|"requests reformulation"| node_groqservice
node_groqservice -.->|"calls inference"| node_groqcloud
node_hybrid -->|"searches dense index"| node_vector
node_dataset -->|"loads corpus"| node_vector
node_routes -->|"parses uploads"| node_parser
node_parser -->|"provides text"| node_chunker
node_routes -->|"indexes uploads"| node_vector
node_routes -->|"runs evaluation"| node_eval
node_eval -->|"evaluates queries"| node_rag
node_eval -->|"computes scores"| node_metrics
node_eval -->|"judges answers"| node_judge
node_judge -->|"requests assessment"| node_groqservice

click node_ui "https://github.com/rk0297/legal-chatbot/blob/main/server/static/index.html"
click node_main "https://github.com/rk0297/legal-chatbot/blob/main/server/main.py"
click node_routes "https://github.com/rk0297/legal-chatbot/blob/main/server/api/routes.py"
click node_schemas "https://github.com/rk0297/legal-chatbot/blob/main/server/api/schemas.py"
click node_rag "https://github.com/rk0297/legal-chatbot/blob/main/server/services/rag_service.py"
click node_selfquery "https://github.com/rk0297/legal-chatbot/blob/main/server/services/self_query_service.py"
click node_guardrails "https://github.com/rk0297/legal-chatbot/blob/main/server/services/guardrails.py"
click node_groqservice "https://github.com/rk0297/legal-chatbot/blob/main/server/services/groq_service.py"
click node_hybrid "https://github.com/rk0297/legal-chatbot/blob/main/server/db/hybrid_search.py"
click node_vector "https://github.com/rk0297/legal-chatbot/blob/main/server/db/vector_store.py"
click node_dataset "https://github.com/rk0297/legal-chatbot/blob/main/server/ingestion/dataset_loader.py"
click node_parser "https://github.com/rk0297/legal-chatbot/blob/main/server/ingestion/document_parser.py"
click node_chunker "https://github.com/rk0297/legal-chatbot/blob/main/server/ingestion/chunking.py"
click node_eval "https://github.com/rk0297/legal-chatbot/blob/main/server/evaluation/evaluator.py"
click node_metrics "https://github.com/rk0297/legal-chatbot/blob/main/server/evaluation/metrics.py"
click node_judge "https://github.com/rk0297/legal-chatbot/blob/main/server/evaluation/llm_judge.py"

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_ui,node_user toneBlue
class node_main,node_routes,node_schemas toneAmber
class node_rag,node_selfquery,node_guardrails,node_groqservice toneMint
class node_hybrid,node_vector,node_dataset,node_parser,node_chunker toneRose
class node_eval,node_metrics,node_judge,node_groqcloud toneIndigo
```

## Components

### Client

- [Web interface](https://github.com/rk0297/legal-chatbot/blob/main/server/static/index.html): `server/static/index.html`

### API

- [App runtime](https://github.com/rk0297/legal-chatbot/blob/main/server/main.py): `server/main.py`
- [API routes](https://github.com/rk0297/legal-chatbot/blob/main/server/api/routes.py): `server/api/routes.py`
- [API schemas](https://github.com/rk0297/legal-chatbot/blob/main/server/api/schemas.py): `server/api/schemas.py`

### Consultation

- [RAG orchestration](https://github.com/rk0297/legal-chatbot/blob/main/server/services/rag_service.py): `server/services/rag_service.py`
- [Query reformulation](https://github.com/rk0297/legal-chatbot/blob/main/server/services/self_query_service.py): `server/services/self_query_service.py`
- [Legal guardrails](https://github.com/rk0297/legal-chatbot/blob/main/server/services/guardrails.py): `server/services/guardrails.py`
- [Inference client](https://github.com/rk0297/legal-chatbot/blob/main/server/services/groq_service.py): `server/services/groq_service.py`

### Legal Knowledge

- [Hybrid retrieval](https://github.com/rk0297/legal-chatbot/blob/main/server/db/hybrid_search.py): `server/db/hybrid_search.py`
- [Vector store](https://github.com/rk0297/legal-chatbot/blob/main/server/db/vector_store.py): `server/db/vector_store.py`
- [Corpus loading](https://github.com/rk0297/legal-chatbot/blob/main/server/ingestion/dataset_loader.py): `server/ingestion/dataset_loader.py`
- [Document parsing](https://github.com/rk0297/legal-chatbot/blob/main/server/ingestion/document_parser.py): `server/ingestion/document_parser.py`
- [Legal chunking](https://github.com/rk0297/legal-chatbot/blob/main/server/ingestion/chunking.py): `server/ingestion/chunking.py`

### Evaluation

- [RAG evaluator](https://github.com/rk0297/legal-chatbot/blob/main/server/evaluation/evaluator.py): `server/evaluation/evaluator.py`
- [IR metrics](https://github.com/rk0297/legal-chatbot/blob/main/server/evaluation/metrics.py): `server/evaluation/metrics.py`
- [LLM judge](https://github.com/rk0297/legal-chatbot/blob/main/server/evaluation/llm_judge.py): `server/evaluation/llm_judge.py`

### Other components

- **Legal user**
- **Groq Cloud**

## Connections

- Legal user → Web interface: asks question
- Web interface → API routes: sends requests
- App runtime → API routes: mounts API
- App runtime → Web interface: serves UI
- API routes → RAG orchestration: delegates chat
- RAG orchestration → Query reformulation: reformulates
- RAG orchestration → Hybrid retrieval: retrieves context
- RAG orchestration → Legal guardrails: checks distress
- RAG orchestration → Inference client: generates answer
- Query reformulation → Inference client: requests reformulation
- Inference client → Groq Cloud: calls inference
- Hybrid retrieval → Vector store: searches dense index
- Corpus loading → Vector store: loads corpus
- API routes → Document parsing: parses uploads
- Document parsing → Legal chunking: provides text
- API routes → Vector store: indexes uploads
- API routes → RAG evaluator: runs evaluation
- RAG evaluator → RAG orchestration: evaluates queries
- RAG evaluator → IR metrics: computes scores
- RAG evaluator → LLM judge: judges answers
- LLM judge → Inference client: requests assessment