# rachit101-cell/legal-lens architecture

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

- Interactive diagram: https://gitdiagram.com/rachit101-cell/legal-lens
- Repository: https://github.com/rachit101-cell/legal-lens

## Overview

LegalLens is a web application for turning uploaded legal agreements into cited risks, obligations, timelines, and grounded answers. The principal workflow runs from upload through document extraction and clause analysis, then presents results in the dashboard or answers document-specific chat questions. The README describes redlines, party/obligation mapping, and evidence verification as product capabilities; the graph includes their supported modules, but several route and service implementations were not sampled, so uncertain call wiring is omitted.

Main entry points: [`apps/api/app/services/intelligence_engine.py`](https://github.com/rachit101-cell/legal-lens/blob/main/apps/api/app/services/intelligence_engine.py) (Intelligence engine), [`apps/api/app/services/document_engine.py`](https://github.com/rachit101-cell/legal-lens/blob/main/apps/api/app/services/document_engine.py) (Document engine), [`apps/api/app/main.py`](https://github.com/rachit101-cell/legal-lens/blob/main/apps/api/app/main.py) (FastAPI application), [`apps/api/app/api/chat.py`](https://github.com/rachit101-cell/legal-lens/blob/main/apps/api/app/api/chat.py) (Chat endpoints)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web client"]
  node_web["LegalLens web app"]
  node_webapi["API client<br/>[api.ts]"]
end

subgraph group_api["API workflows"]
  node_apiapp["FastAPI application<br/>[main.py]"]
  node_documents["Document endpoints<br/>[documents.py]"]
  node_analysisapi["Analysis endpoints<br/>[analysis.py]"]
  node_chatapi["Chat endpoints<br/>[chat.py]"]
end

subgraph group_ingestion["Document ingestion"]
  node_upload["Upload service<br/>[upload_service.py]"]
  node_docengine["Document engine<br/>[document_engine.py]"]
  node_pdf["PDF parser<br/>[pdf_parser.py]"]
  node_docx["DOCX parser<br/>[docx_parser.py]"]
  node_ocr["OCR parser<br/>[ocr_parser.py]"]
end

subgraph group_analysis["Legal intelligence"]
  node_intelligence["Intelligence engine"]
  node_segmentation["Segmentation<br/>[segmentation.py]"]
  node_taxonomy["Clause taxonomy<br/>[taxonomy.py]"]
  node_entities["Entity extraction"]
  node_findings["Risk findings<br/>[finding_engine.py]"]
  node_timeline["Contract timeline<br/>[timeline_engine.py]"]
  node_retrieval["Clause retrieval"]
  node_generation["AI generation<br/>[generation.py]"]
  node_verification["Evidence verification"]
end

subgraph group_persistence["Data and integrations"]
  node_analysisrepo["Analysis repository<br/>[analysis_repo.py]"]
  node_docrepo["Document repository<br/>[document_repo.py]"]
  node_db[("PostgreSQL database<br/>[session.py]")]
  node_storage["Object storage service<br/>[storage.py]"]
end

node_user(("Contract reviewer"))
node_s3[("S3-compatible storage")]
node_llm{{"Hosted model providers"}}

node_user -->|"uploads and reviews"| node_web
node_web -->|"requests API"| node_webapi
node_webapi -->|"sends REST requests"| node_apiapp
node_apiapp -->|"dispatches document requests"| node_documents
node_apiapp -->|"dispatches analysis requests"| node_analysisapi
node_apiapp -->|"dispatches chat requests"| node_chatapi
node_documents -->|"handles uploads"| node_upload
node_upload -->|"stores file"| node_storage
node_storage -->|"reads and writes objects"| node_s3
node_docengine -->|"loads and updates document"| node_docrepo
node_docengine -->|"downloads file"| node_storage
node_docengine -->|"parses PDF"| node_pdf
node_docengine -->|"parses DOCX"| node_docx
node_docengine -->|"parses scanned content"| node_ocr
node_docengine -->|"saves pages and clauses"| node_db
node_analysisapi -->|"runs analysis"| node_intelligence
node_intelligence -->|"reads document pages"| node_db
node_intelligence -->|"segments pages"| node_segmentation
node_intelligence -->|"classifies clauses"| node_taxonomy
node_intelligence -->|"extracts entities"| node_entities
node_intelligence -->|"generates risks"| node_findings
node_intelligence -->|"generates events"| node_timeline
node_intelligence -->|"saves analysis records"| node_analysisrepo
node_analysisrepo -->|"persists results"| node_db
node_chatapi -->|"searches clauses"| node_retrieval
node_retrieval -->|"reads clauses"| node_db
node_chatapi -->|"generates answer"| node_generation
node_generation -.->|"requests completion"| node_llm
node_chatapi -->|"checks cited claims"| node_verification
node_verification -->|"uses evidence clauses"| node_retrieval

click node_web "https://github.com/rachit101-cell/legal-lens/tree/main/apps/web/app"
click node_webapi "https://github.com/rachit101-cell/legal-lens/blob/main/apps/web/lib/api.ts"
click node_apiapp "https://github.com/rachit101-cell/legal-lens/blob/main/apps/api/app/main.py"
click node_documents "https://github.com/rachit101-cell/legal-lens/blob/main/apps/api/app/api/documents.py"
click node_analysisapi "https://github.com/rachit101-cell/legal-lens/blob/main/apps/api/app/api/analysis.py"
click node_chatapi "https://github.com/rachit101-cell/legal-lens/blob/main/apps/api/app/api/chat.py"
click node_upload "https://github.com/rachit101-cell/legal-lens/blob/main/apps/api/app/services/upload_service.py"
click node_docengine "https://github.com/rachit101-cell/legal-lens/blob/main/apps/api/app/services/document_engine.py"
click node_pdf "https://github.com/rachit101-cell/legal-lens/blob/main/apps/api/app/services/parsers/pdf_parser.py"
click node_docx "https://github.com/rachit101-cell/legal-lens/blob/main/apps/api/app/services/parsers/docx_parser.py"
click node_ocr "https://github.com/rachit101-cell/legal-lens/blob/main/apps/api/app/services/parsers/ocr_parser.py"
click node_intelligence "https://github.com/rachit101-cell/legal-lens/blob/main/apps/api/app/services/intelligence_engine.py"
click node_segmentation "https://github.com/rachit101-cell/legal-lens/blob/main/apps/api/app/services/intelligence/segmentation.py"
click node_taxonomy "https://github.com/rachit101-cell/legal-lens/blob/main/apps/api/app/services/intelligence/taxonomy.py"
click node_entities "https://github.com/rachit101-cell/legal-lens/blob/main/apps/api/app/services/intelligence/entity_extraction.py"
click node_findings "https://github.com/rachit101-cell/legal-lens/blob/main/apps/api/app/services/analysis/finding_engine.py"
click node_timeline "https://github.com/rachit101-cell/legal-lens/blob/main/apps/api/app/services/analysis/timeline_engine.py"
click node_retrieval "https://github.com/rachit101-cell/legal-lens/blob/main/apps/api/app/services/retrieval/retrieval_engine.py"
click node_generation "https://github.com/rachit101-cell/legal-lens/blob/main/apps/api/app/services/ai/generation.py"
click node_verification "https://github.com/rachit101-cell/legal-lens/blob/main/apps/api/app/services/evidence/verification_engine.py"
click node_analysisrepo "https://github.com/rachit101-cell/legal-lens/blob/main/apps/api/app/repositories/analysis_repo.py"
click node_docrepo "https://github.com/rachit101-cell/legal-lens/blob/main/apps/api/app/repositories/document_repo.py"
click node_db "https://github.com/rachit101-cell/legal-lens/blob/main/apps/api/app/db/session.py"
click node_storage "https://github.com/rachit101-cell/legal-lens/blob/main/apps/api/app/services/storage.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_web,node_webapi,node_user toneBlue
class node_apiapp,node_documents,node_analysisapi,node_chatapi,node_s3 toneAmber
class node_upload,node_docengine,node_pdf,node_docx,node_ocr toneMint
class node_intelligence,node_segmentation,node_taxonomy,node_entities,node_findings,node_timeline,node_retrieval,node_generation,node_verification toneRose
class node_analysisrepo,node_docrepo,node_db,node_storage,node_llm toneIndigo
```

## Components

### Web client

- [LegalLens web app](https://github.com/rachit101-cell/legal-lens/tree/main/apps/web/app): `apps/web/app`
- [API client](https://github.com/rachit101-cell/legal-lens/blob/main/apps/web/lib/api.ts): `apps/web/lib/api.ts`

### API workflows

- [FastAPI application](https://github.com/rachit101-cell/legal-lens/blob/main/apps/api/app/main.py): `apps/api/app/main.py`
- [Document endpoints](https://github.com/rachit101-cell/legal-lens/blob/main/apps/api/app/api/documents.py): `apps/api/app/api/documents.py`
- [Analysis endpoints](https://github.com/rachit101-cell/legal-lens/blob/main/apps/api/app/api/analysis.py): `apps/api/app/api/analysis.py`
- [Chat endpoints](https://github.com/rachit101-cell/legal-lens/blob/main/apps/api/app/api/chat.py): `apps/api/app/api/chat.py`

### Document ingestion

- [Upload service](https://github.com/rachit101-cell/legal-lens/blob/main/apps/api/app/services/upload_service.py): `apps/api/app/services/upload_service.py`
- [Document engine](https://github.com/rachit101-cell/legal-lens/blob/main/apps/api/app/services/document_engine.py): `apps/api/app/services/document_engine.py`
- [PDF parser](https://github.com/rachit101-cell/legal-lens/blob/main/apps/api/app/services/parsers/pdf_parser.py): `apps/api/app/services/parsers/pdf_parser.py`
- [DOCX parser](https://github.com/rachit101-cell/legal-lens/blob/main/apps/api/app/services/parsers/docx_parser.py): `apps/api/app/services/parsers/docx_parser.py`
- [OCR parser](https://github.com/rachit101-cell/legal-lens/blob/main/apps/api/app/services/parsers/ocr_parser.py): `apps/api/app/services/parsers/ocr_parser.py`

### Legal intelligence

- [Intelligence engine](https://github.com/rachit101-cell/legal-lens/blob/main/apps/api/app/services/intelligence_engine.py): `apps/api/app/services/intelligence_engine.py`
- [Segmentation](https://github.com/rachit101-cell/legal-lens/blob/main/apps/api/app/services/intelligence/segmentation.py): `apps/api/app/services/intelligence/segmentation.py`
- [Clause taxonomy](https://github.com/rachit101-cell/legal-lens/blob/main/apps/api/app/services/intelligence/taxonomy.py): `apps/api/app/services/intelligence/taxonomy.py`
- [Entity extraction](https://github.com/rachit101-cell/legal-lens/blob/main/apps/api/app/services/intelligence/entity_extraction.py): `apps/api/app/services/intelligence/entity_extraction.py`
- [Risk findings](https://github.com/rachit101-cell/legal-lens/blob/main/apps/api/app/services/analysis/finding_engine.py): `apps/api/app/services/analysis/finding_engine.py`
- [Contract timeline](https://github.com/rachit101-cell/legal-lens/blob/main/apps/api/app/services/analysis/timeline_engine.py): `apps/api/app/services/analysis/timeline_engine.py`
- [Clause retrieval](https://github.com/rachit101-cell/legal-lens/blob/main/apps/api/app/services/retrieval/retrieval_engine.py): `apps/api/app/services/retrieval/retrieval_engine.py`
- [AI generation](https://github.com/rachit101-cell/legal-lens/blob/main/apps/api/app/services/ai/generation.py): `apps/api/app/services/ai/generation.py`
- [Evidence verification](https://github.com/rachit101-cell/legal-lens/blob/main/apps/api/app/services/evidence/verification_engine.py): `apps/api/app/services/evidence/verification_engine.py`

### Data and integrations

- [Analysis repository](https://github.com/rachit101-cell/legal-lens/blob/main/apps/api/app/repositories/analysis_repo.py): `apps/api/app/repositories/analysis_repo.py`
- [Document repository](https://github.com/rachit101-cell/legal-lens/blob/main/apps/api/app/repositories/document_repo.py): `apps/api/app/repositories/document_repo.py`
- [PostgreSQL database](https://github.com/rachit101-cell/legal-lens/blob/main/apps/api/app/db/session.py): `apps/api/app/db/session.py`
- [Object storage service](https://github.com/rachit101-cell/legal-lens/blob/main/apps/api/app/services/storage.py): `apps/api/app/services/storage.py`

### Other components

- **Contract reviewer**
- **S3-compatible storage**
- **Hosted model providers**

## Connections

- Contract reviewer → LegalLens web app: uploads and reviews
- LegalLens web app → API client: requests API
- API client → FastAPI application: sends REST requests
- FastAPI application → Document endpoints: dispatches document requests
- FastAPI application → Analysis endpoints: dispatches analysis requests
- FastAPI application → Chat endpoints: dispatches chat requests
- Document endpoints → Upload service: handles uploads
- Upload service → Object storage service: stores file
- Object storage service → S3-compatible storage: reads and writes objects
- Document engine → Document repository: loads and updates document
- Document engine → Object storage service: downloads file
- Document engine → PDF parser: parses PDF
- Document engine → DOCX parser: parses DOCX
- Document engine → OCR parser: parses scanned content
- Document engine → PostgreSQL database: saves pages and clauses
- Analysis endpoints → Intelligence engine: runs analysis
- Intelligence engine → PostgreSQL database: reads document pages
- Intelligence engine → Segmentation: segments pages
- Intelligence engine → Clause taxonomy: classifies clauses
- Intelligence engine → Entity extraction: extracts entities
- Intelligence engine → Risk findings: generates risks
- Intelligence engine → Contract timeline: generates events
- Intelligence engine → Analysis repository: saves analysis records
- Analysis repository → PostgreSQL database: persists results
- Chat endpoints → Clause retrieval: searches clauses
- Clause retrieval → PostgreSQL database: reads clauses
- Chat endpoints → AI generation: generates answer
- AI generation → Hosted model providers: requests completion
- Chat endpoints → Evidence verification: checks cited claims
- Evidence verification → Clause retrieval: uses evidence clauses