# adityaa2404/legal-assist architecture

> Architecture diagram of the GitHub repository adityaa2404/legal-assist, 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/adityaa2404/legal-assist
- Repository: https://github.com/adityaa2404/legal-assist

## Overview

Legal Assist AI turns uploaded contracts and case files into privacy-preserving analyses, clause breakdowns, grounded chat, and reports. The main workflow runs from the user’s upload through extraction/OCR, PII anonymization, session storage and background retrieval-index construction, then analysis or chat and results in the UI. Separate branches support authentication, document comparison, clause-library browsing, and permanent history. The README documents these capabilities and the worker pipeline; sampled source confirms API routing, session persistence, report tasks, and frontend streaming, but not every endpoint-to-service call.

Main entry points: [`backend/app/worker/tasks.py`](https://github.com/adityaa2404/legal-assist/blob/main/backend/app/worker/tasks.py) (Background tasks), [`backend/app/api/v1/router.py`](https://github.com/adityaa2404/legal-assist/blob/main/backend/app/api/v1/router.py) (API routes), [`frontend/src/App.tsx`](https://github.com/adityaa2404/legal-assist/blob/main/frontend/src/App.tsx) (React app and routes), [`backend/app/api/v1/analysis.py`](https://github.com/adityaa2404/legal-assist/blob/main/backend/app/api/v1/analysis.py) (Analysis endpoints)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["User interface"]
  node_app["React app and routes<br/>[App.tsx]"]
  node_upload_ui["Upload and capture<br/>[UploadView.tsx]"]
  node_results_ui["Analysis and document views"]
  node_chat_ui["Chat interface<br/>[useChat.ts]"]
  node_history_ui["History and clauses<br/>[HistoryPage.tsx]"]
  node_api_client["API client<br/>[axiosClient.ts]"]
end

subgraph group_api["HTTP API"]
  node_backend["FastAPI application<br/>[main.py]"]
  node_router["API routes<br/>[router.py]"]
  node_documents["Document endpoints<br/>[documents.py]"]
  node_analysis_api["Analysis endpoints<br/>[analysis.py]"]
  node_chat_api["Chat endpoints<br/>[chat.py]"]
  node_history_api["History endpoints<br/>[history.py]"]
  node_comparison_api["Comparison endpoints<br/>[comparison.py]"]
  node_clause_api["Clause library endpoints<br/>[clause_library.py]"]
  node_auth_api["Authentication endpoints<br/>[auth.py]"]
end

subgraph group_processing["Document processing"]
  node_worker["Background tasks<br/>[tasks.py]"]
  node_parser["Document extraction and OCR<br/>[document_parser.py]"]
  node_privacy["PII anonymization<br/>[pii_anonymizer.py]"]
  node_htoc["HTOC construction<br/>[htoc_builder.py]"]
  node_bm25["BM25 retrieval<br/>[bm25_search.py]"]
  node_tree_search["Tree retrieval<br/>[tree_search.py]"]
  node_llm["LLM provider client<br/>[gemini_client.py]"]
end

subgraph group_state["Persistence and queue"]
  node_sessions["Session service<br/>[session_service.py]"]
  node_mongo[("MongoDB<br/>[database.py]")]
  node_redis["Redis task broker<br/>[redis.py]"]
end

subgraph group_features["Analysis features"]
  node_auth_service["Authentication service<br/>[auth_service.py]"]
  node_report["PDF report generation"]
  node_clause_service["Clause library service"]
  node_history_service["History service<br/>[history_service.py]"]
end

node_user(("User"))

node_user -->|"uses"| node_app
node_app -->|"routes to"| node_upload_ui
node_app -->|"routes to"| node_results_ui
node_app -->|"routes to"| node_chat_ui
node_app -->|"routes to"| node_history_ui
node_upload_ui -->|"uploads via"| node_api_client
node_results_ui -->|"requests via"| node_api_client
node_chat_ui -->|"streams via"| node_api_client
node_history_ui -->|"requests via"| node_api_client
node_api_client -->|"HTTP requests"| node_backend
node_backend -->|"mounts routes"| node_router
node_router -->|"dispatches"| node_documents
node_router -->|"dispatches"| node_analysis_api
node_router -->|"dispatches"| node_chat_api
node_router -->|"dispatches"| node_history_api
node_router -->|"dispatches"| node_comparison_api
node_router -->|"dispatches"| node_clause_api
node_router -->|"dispatches"| node_auth_api
node_documents -->|"queues processing"| node_worker
node_worker -->|"consumes jobs"| node_redis
node_worker -->|"extracts text"| node_parser
node_worker -->|"anonymizes text"| node_privacy
node_worker -->|"builds structure"| node_htoc
node_worker -->|"builds index"| node_bm25
node_worker -->|"updates session"| node_sessions
node_analysis_api -->|"deanonymizes results"| node_privacy
node_analysis_api -->|"requests analysis"| node_llm
node_analysis_api -->|"retrieves context"| node_tree_search
node_chat_api -->|"searches index"| node_bm25
node_chat_api -->|"retrieves context"| node_tree_search
node_chat_api -->|"generates answers"| node_llm
node_chat_api -->|"deanonymizes answers"| node_privacy
node_tree_search -->|"navigates tree"| node_htoc
node_tree_search -->|"selects sections"| node_llm
node_analysis_api -->|"queues reports"| node_worker
node_worker -->|"renders PDF"| node_report
node_worker -->|"caches report"| node_sessions
node_history_api -->|"serves history"| node_history_service
node_history_service -->|"reads history"| node_mongo
node_sessions -->|"reads and writes"| node_mongo
node_auth_api -->|"authenticates"| node_auth_service
node_auth_service -->|"reads and writes users"| node_mongo
node_clause_api -->|"serves library"| node_clause_service
node_clause_service -->|"reads and writes"| node_mongo
node_comparison_api -.->|"compares documents"| node_llm
node_llm -.-> node_user

click node_app "https://github.com/adityaa2404/legal-assist/blob/main/frontend/src/App.tsx"
click node_upload_ui "https://github.com/adityaa2404/legal-assist/blob/main/frontend/src/components/UploadView.tsx"
click node_results_ui "https://github.com/adityaa2404/legal-assist/blob/main/frontend/src/components/AnalysisDashboard.tsx"
click node_chat_ui "https://github.com/adityaa2404/legal-assist/blob/main/frontend/src/hooks/useChat.ts"
click node_history_ui "https://github.com/adityaa2404/legal-assist/blob/main/frontend/src/components/HistoryPage.tsx"
click node_api_client "https://github.com/adityaa2404/legal-assist/blob/main/frontend/src/api/axiosClient.ts"
click node_backend "https://github.com/adityaa2404/legal-assist/blob/main/backend/app/main.py"
click node_router "https://github.com/adityaa2404/legal-assist/blob/main/backend/app/api/v1/router.py"
click node_documents "https://github.com/adityaa2404/legal-assist/blob/main/backend/app/api/v1/documents.py"
click node_analysis_api "https://github.com/adityaa2404/legal-assist/blob/main/backend/app/api/v1/analysis.py"
click node_chat_api "https://github.com/adityaa2404/legal-assist/blob/main/backend/app/api/v1/chat.py"
click node_history_api "https://github.com/adityaa2404/legal-assist/blob/main/backend/app/api/v1/history.py"
click node_comparison_api "https://github.com/adityaa2404/legal-assist/blob/main/backend/app/api/v1/comparison.py"
click node_clause_api "https://github.com/adityaa2404/legal-assist/blob/main/backend/app/api/v1/clause_library.py"
click node_worker "https://github.com/adityaa2404/legal-assist/blob/main/backend/app/worker/tasks.py"
click node_parser "https://github.com/adityaa2404/legal-assist/blob/main/backend/app/services/document_parser.py"
click node_privacy "https://github.com/adityaa2404/legal-assist/blob/main/backend/app/services/pii_anonymizer.py"
click node_htoc "https://github.com/adityaa2404/legal-assist/blob/main/backend/app/services/htoc_builder.py"
click node_bm25 "https://github.com/adityaa2404/legal-assist/blob/main/backend/app/services/bm25_search.py"
click node_tree_search "https://github.com/adityaa2404/legal-assist/blob/main/backend/app/services/tree_search.py"
click node_llm "https://github.com/adityaa2404/legal-assist/blob/main/backend/app/services/gemini_client.py"
click node_sessions "https://github.com/adityaa2404/legal-assist/blob/main/backend/app/services/session_service.py"
click node_mongo "https://github.com/adityaa2404/legal-assist/blob/main/backend/app/core/database.py"
click node_redis "https://github.com/adityaa2404/legal-assist/blob/main/backend/app/core/redis.py"
click node_auth_api "https://github.com/adityaa2404/legal-assist/blob/main/backend/app/api/v1/auth.py"
click node_auth_service "https://github.com/adityaa2404/legal-assist/blob/main/backend/app/services/auth_service.py"
click node_report "https://github.com/adityaa2404/legal-assist/blob/main/backend/app/services/report_generator.py"
click node_clause_service "https://github.com/adityaa2404/legal-assist/blob/main/backend/app/services/clause_library_service.py"
click node_history_service "https://github.com/adityaa2404/legal-assist/blob/main/backend/app/services/history_service.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_app,node_upload_ui,node_results_ui,node_chat_ui,node_history_ui,node_api_client,node_user toneBlue
class node_backend,node_router,node_documents,node_analysis_api,node_chat_api,node_history_api,node_comparison_api,node_clause_api,node_auth_api toneAmber
class node_worker,node_parser,node_privacy,node_htoc,node_bm25,node_tree_search,node_llm toneMint
class node_sessions,node_mongo,node_redis toneRose
class node_auth_service,node_report,node_clause_service,node_history_service toneIndigo
```

## Components

### User interface

- [React app and routes](https://github.com/adityaa2404/legal-assist/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Upload and capture](https://github.com/adityaa2404/legal-assist/blob/main/frontend/src/components/UploadView.tsx): `frontend/src/components/UploadView.tsx`
- [Analysis and document views](https://github.com/adityaa2404/legal-assist/blob/main/frontend/src/components/AnalysisDashboard.tsx): `frontend/src/components/AnalysisDashboard.tsx`
- [Chat interface](https://github.com/adityaa2404/legal-assist/blob/main/frontend/src/hooks/useChat.ts): `frontend/src/hooks/useChat.ts`
- [History and clauses](https://github.com/adityaa2404/legal-assist/blob/main/frontend/src/components/HistoryPage.tsx): `frontend/src/components/HistoryPage.tsx`
- [API client](https://github.com/adityaa2404/legal-assist/blob/main/frontend/src/api/axiosClient.ts): `frontend/src/api/axiosClient.ts`

### HTTP API

- [FastAPI application](https://github.com/adityaa2404/legal-assist/blob/main/backend/app/main.py): `backend/app/main.py`
- [API routes](https://github.com/adityaa2404/legal-assist/blob/main/backend/app/api/v1/router.py): `backend/app/api/v1/router.py`
- [Document endpoints](https://github.com/adityaa2404/legal-assist/blob/main/backend/app/api/v1/documents.py): `backend/app/api/v1/documents.py`
- [Analysis endpoints](https://github.com/adityaa2404/legal-assist/blob/main/backend/app/api/v1/analysis.py): `backend/app/api/v1/analysis.py`
- [Chat endpoints](https://github.com/adityaa2404/legal-assist/blob/main/backend/app/api/v1/chat.py): `backend/app/api/v1/chat.py`
- [History endpoints](https://github.com/adityaa2404/legal-assist/blob/main/backend/app/api/v1/history.py): `backend/app/api/v1/history.py`
- [Comparison endpoints](https://github.com/adityaa2404/legal-assist/blob/main/backend/app/api/v1/comparison.py): `backend/app/api/v1/comparison.py`
- [Clause library endpoints](https://github.com/adityaa2404/legal-assist/blob/main/backend/app/api/v1/clause_library.py): `backend/app/api/v1/clause_library.py`
- [Authentication endpoints](https://github.com/adityaa2404/legal-assist/blob/main/backend/app/api/v1/auth.py): `backend/app/api/v1/auth.py`

### Document processing

- [Background tasks](https://github.com/adityaa2404/legal-assist/blob/main/backend/app/worker/tasks.py): `backend/app/worker/tasks.py`
- [Document extraction and OCR](https://github.com/adityaa2404/legal-assist/blob/main/backend/app/services/document_parser.py): `backend/app/services/document_parser.py`
- [PII anonymization](https://github.com/adityaa2404/legal-assist/blob/main/backend/app/services/pii_anonymizer.py): `backend/app/services/pii_anonymizer.py`
- [HTOC construction](https://github.com/adityaa2404/legal-assist/blob/main/backend/app/services/htoc_builder.py): `backend/app/services/htoc_builder.py`
- [BM25 retrieval](https://github.com/adityaa2404/legal-assist/blob/main/backend/app/services/bm25_search.py): `backend/app/services/bm25_search.py`
- [Tree retrieval](https://github.com/adityaa2404/legal-assist/blob/main/backend/app/services/tree_search.py): `backend/app/services/tree_search.py`
- [LLM provider client](https://github.com/adityaa2404/legal-assist/blob/main/backend/app/services/gemini_client.py): `backend/app/services/gemini_client.py`

### Persistence and queue

- [Session service](https://github.com/adityaa2404/legal-assist/blob/main/backend/app/services/session_service.py): `backend/app/services/session_service.py`
- [MongoDB](https://github.com/adityaa2404/legal-assist/blob/main/backend/app/core/database.py): `backend/app/core/database.py`
- [Redis task broker](https://github.com/adityaa2404/legal-assist/blob/main/backend/app/core/redis.py): `backend/app/core/redis.py`

### Analysis features

- [Authentication service](https://github.com/adityaa2404/legal-assist/blob/main/backend/app/services/auth_service.py): `backend/app/services/auth_service.py`
- [PDF report generation](https://github.com/adityaa2404/legal-assist/blob/main/backend/app/services/report_generator.py): `backend/app/services/report_generator.py`
- [Clause library service](https://github.com/adityaa2404/legal-assist/blob/main/backend/app/services/clause_library_service.py): `backend/app/services/clause_library_service.py`
- [History service](https://github.com/adityaa2404/legal-assist/blob/main/backend/app/services/history_service.py): `backend/app/services/history_service.py`

### Other components

- **User**

## Connections

- User → React app and routes: uses
- React app and routes → Upload and capture: routes to
- React app and routes → Analysis and document views: routes to
- React app and routes → Chat interface: routes to
- React app and routes → History and clauses: routes to
- Upload and capture → API client: uploads via
- Analysis and document views → API client: requests via
- Chat interface → API client: streams via
- History and clauses → API client: requests via
- API client → FastAPI application: HTTP requests
- FastAPI application → API routes: mounts routes
- API routes → Document endpoints: dispatches
- API routes → Analysis endpoints: dispatches
- API routes → Chat endpoints: dispatches
- API routes → History endpoints: dispatches
- API routes → Comparison endpoints: dispatches
- API routes → Clause library endpoints: dispatches
- API routes → Authentication endpoints: dispatches
- Document endpoints → Background tasks: queues processing
- Background tasks → Redis task broker: consumes jobs
- Background tasks → Document extraction and OCR: extracts text
- Background tasks → PII anonymization: anonymizes text
- Background tasks → HTOC construction: builds structure
- Background tasks → BM25 retrieval: builds index
- Background tasks → Session service: updates session
- Analysis endpoints → PII anonymization: deanonymizes results
- Analysis endpoints → LLM provider client: requests analysis
- Analysis endpoints → Tree retrieval: retrieves context
- Chat endpoints → BM25 retrieval: searches index
- Chat endpoints → Tree retrieval: retrieves context
- Chat endpoints → LLM provider client: generates answers
- Chat endpoints → PII anonymization: deanonymizes answers
- Tree retrieval → HTOC construction: navigates tree
- Tree retrieval → LLM provider client: selects sections
- Analysis endpoints → Background tasks: queues reports
- Background tasks → PDF report generation: renders PDF
- Background tasks → Session service: caches report
- History endpoints → History service: serves history
- History service → MongoDB: reads history
- Session service → MongoDB: reads and writes
- Authentication endpoints → Authentication service: authenticates
- Authentication service → MongoDB: reads and writes users
- Clause library endpoints → Clause library service: serves library
- Clause library service → MongoDB: reads and writes
- Comparison endpoints → LLM provider client: compares documents
- LLM provider client → User