# devantaris/ai-legal-document-intelligence-system architecture

> Architecture diagram of the GitHub repository devantaris/ai-legal-document-intelligence-system, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/devantaris/ai-legal-document-intelligence-system
- Repository: https://github.com/devantaris/ai-legal-document-intelligence-system

## Overview

LegalIQ is a multi-user legal-document analysis application. Users authenticate, upload contracts, and follow their ingestion status; once processing finishes, they can ask cited questions, inspect summaries, key terms and classified clauses, or compare two documents. The backend extracts page-aware text, chunks and embeds it, then stores it for retrieval and analysis. The README documents PostgreSQL/pgvector and local file storage, plus Z.ai and Ollama providers. Relationships for unsampled analysis services and storage are shown only where the README or source index supports them.

Main entry points: [`backend/app/services/llm/__init__.py`](https://github.com/devantaris/ai-legal-document-intelligence-system/blob/main/backend/app/services/llm/__init__.py) (Provider selection), [`backend/app/api/router.py`](https://github.com/devantaris/ai-legal-document-intelligence-system/blob/main/backend/app/api/router.py) (API router), [`backend/app/core/database.py`](https://github.com/devantaris/ai-legal-document-intelligence-system/blob/main/backend/app/core/database.py) (PostgreSQL and pgvector), [`frontend/src/App.tsx`](https://github.com/devantaris/ai-legal-document-intelligence-system/blob/main/frontend/src/App.tsx) (App routing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Web application"]
  node_app["App routing<br/>[App.tsx]"]
  node_auth_ui["Auth state<br/>[auth.ts]"]
  node_api_client["API client<br/>[api.ts]"]
  node_dashboard["Document dashboard<br/>[DashboardPage.tsx]"]
  node_document_ui["Document workspace<br/>[DocumentPage.tsx]"]
  node_analysis_panels["Analysis panels<br/>[SummaryPanel.tsx]"]
  node_chat_panel["Chat panel<br/>[ChatPanel.tsx]"]
  node_compare_ui["Compare page<br/>[ComparePage.tsx]"]
end

subgraph group_api["API and access"]
  node_fastapi["FastAPI application<br/>[main.py]"]
  node_api_router["API router<br/>[router.py]"]
  node_auth_api["Authentication routes<br/>[auth.py]"]
  node_document_api["Document routes<br/>[documents.py]"]
  node_chat_api["Chat routes<br/>[chat.py]"]
  node_analysis_api["Analysis routes<br/>[analysis.py]"]
  node_compare_api["Comparison routes<br/>[compare.py]"]
end

subgraph group_processing["Document intelligence"]
  node_ingestion["Ingestion orchestrator<br/>[ingestion.py]"]
  node_extraction["Text extraction<br/>[extraction.py]"]
  node_chunking["Structure-aware chunking<br/>[chunking.py]"]
  node_retrieval["Hybrid retrieval<br/>[retrieval.py]"]
  node_chat_service["RAG chat<br/>[chat.py]"]
  node_summary_service["Summarization<br/>[summarization.py]"]
  node_terms_service["Key-term extraction<br/>[key_terms.py]"]
  node_clauses_service["Clause classification<br/>[clauses.py]"]
  node_compare_service["Clause comparison<br/>[compare.py]"]
end

subgraph group_data["Persistence and models"]
  node_database[("PostgreSQL and pgvector<br/>[database.py]")]
  node_models["Domain models"]
  node_file_storage[("Uploaded files")]
end

subgraph group_integrations["LLM providers"]
  node_provider_layer["Provider selection<br/>[__init__.py]"]
  node_zai["Z.ai provider<br/>[zai.py]"]
  node_ollama["Ollama provider<br/>[ollama.py]"]
end

node_user(("User"))

node_user -->|"uses"| node_app
node_app -->|"checks session"| node_auth_ui
node_app -->|"routes to"| node_dashboard
node_app -->|"routes to"| node_document_ui
node_app -->|"routes to"| node_compare_ui
node_auth_ui -->|"requests auth"| node_api_client
node_dashboard -->|"requests documents"| node_api_client
node_document_ui -->|"renders"| node_analysis_panels
node_document_ui -->|"renders"| node_chat_panel
node_document_ui -->|"requests analysis"| node_api_client
node_compare_ui -->|"requests comparison"| node_api_client
node_api_client -->|"sends HTTP and SSE"| node_fastapi
node_fastapi -->|"mounts routes"| node_api_router
node_api_router -->|"registers"| node_auth_api
node_api_router -->|"registers"| node_document_api
node_api_router -->|"registers"| node_chat_api
node_api_router -->|"registers"| node_analysis_api
node_api_router -->|"registers"| node_compare_api
node_document_api -->|"starts processing"| node_ingestion
node_document_api -->|"stores upload"| node_file_storage
node_ingestion -->|"extracts pages"| node_extraction
node_ingestion -->|"builds chunks"| node_chunking
node_ingestion -->|"embeds chunks"| node_provider_layer
node_ingestion -->|"writes chunks and status"| node_database
node_document_api -->|"persists document"| node_database
node_chat_api -->|"delegates chat"| node_chat_service
node_chat_service -.->|"retrieves context"| node_retrieval
node_retrieval -->|"searches chunks"| node_database
node_retrieval -->|"embeds query"| node_provider_layer
node_chat_service -.->|"generates answer"| node_provider_layer
node_analysis_api -->|"requests summary"| node_summary_service
node_analysis_api -->|"extracts terms"| node_terms_service
node_analysis_api -->|"lists clauses"| node_clauses_service
node_compare_api -->|"compares documents"| node_compare_service
node_summary_service -.->|"uses LLM"| node_provider_layer
node_terms_service -.->|"uses LLM"| node_provider_layer
node_clauses_service -.->|"uses LLM"| node_provider_layer
node_compare_service -.->|"uses LLM"| node_provider_layer
node_analysis_api -->|"reads and stores results"| node_database
node_compare_api -->|"reads clauses"| node_database
node_database -->|"maps domain records"| node_models
node_provider_layer -->|"selects by config"| node_zai
node_provider_layer -->|"selects by config"| node_ollama

click node_app "https://github.com/devantaris/ai-legal-document-intelligence-system/blob/main/frontend/src/App.tsx"
click node_auth_ui "https://github.com/devantaris/ai-legal-document-intelligence-system/blob/main/frontend/src/stores/auth.ts"
click node_api_client "https://github.com/devantaris/ai-legal-document-intelligence-system/blob/main/frontend/src/lib/api.ts"
click node_dashboard "https://github.com/devantaris/ai-legal-document-intelligence-system/blob/main/frontend/src/pages/DashboardPage.tsx"
click node_document_ui "https://github.com/devantaris/ai-legal-document-intelligence-system/blob/main/frontend/src/pages/DocumentPage.tsx"
click node_analysis_panels "https://github.com/devantaris/ai-legal-document-intelligence-system/blob/main/frontend/src/components/SummaryPanel.tsx"
click node_chat_panel "https://github.com/devantaris/ai-legal-document-intelligence-system/blob/main/frontend/src/components/ChatPanel.tsx"
click node_compare_ui "https://github.com/devantaris/ai-legal-document-intelligence-system/blob/main/frontend/src/pages/ComparePage.tsx"
click node_fastapi "https://github.com/devantaris/ai-legal-document-intelligence-system/blob/main/backend/app/main.py"
click node_api_router "https://github.com/devantaris/ai-legal-document-intelligence-system/blob/main/backend/app/api/router.py"
click node_auth_api "https://github.com/devantaris/ai-legal-document-intelligence-system/blob/main/backend/app/api/auth.py"
click node_document_api "https://github.com/devantaris/ai-legal-document-intelligence-system/blob/main/backend/app/api/documents.py"
click node_chat_api "https://github.com/devantaris/ai-legal-document-intelligence-system/blob/main/backend/app/api/chat.py"
click node_analysis_api "https://github.com/devantaris/ai-legal-document-intelligence-system/blob/main/backend/app/api/analysis.py"
click node_compare_api "https://github.com/devantaris/ai-legal-document-intelligence-system/blob/main/backend/app/api/compare.py"
click node_ingestion "https://github.com/devantaris/ai-legal-document-intelligence-system/blob/main/backend/app/services/ingestion.py"
click node_extraction "https://github.com/devantaris/ai-legal-document-intelligence-system/blob/main/backend/app/services/extraction.py"
click node_chunking "https://github.com/devantaris/ai-legal-document-intelligence-system/blob/main/backend/app/services/chunking.py"
click node_retrieval "https://github.com/devantaris/ai-legal-document-intelligence-system/blob/main/backend/app/services/retrieval.py"
click node_chat_service "https://github.com/devantaris/ai-legal-document-intelligence-system/blob/main/backend/app/services/chat.py"
click node_summary_service "https://github.com/devantaris/ai-legal-document-intelligence-system/blob/main/backend/app/services/summarization.py"
click node_terms_service "https://github.com/devantaris/ai-legal-document-intelligence-system/blob/main/backend/app/services/key_terms.py"
click node_clauses_service "https://github.com/devantaris/ai-legal-document-intelligence-system/blob/main/backend/app/services/clauses.py"
click node_compare_service "https://github.com/devantaris/ai-legal-document-intelligence-system/blob/main/backend/app/services/compare.py"
click node_database "https://github.com/devantaris/ai-legal-document-intelligence-system/blob/main/backend/app/core/database.py"
click node_models "https://github.com/devantaris/ai-legal-document-intelligence-system/tree/main/backend/app/models"
click node_provider_layer "https://github.com/devantaris/ai-legal-document-intelligence-system/blob/main/backend/app/services/llm/__init__.py"
click node_zai "https://github.com/devantaris/ai-legal-document-intelligence-system/blob/main/backend/app/services/llm/zai.py"
click node_ollama "https://github.com/devantaris/ai-legal-document-intelligence-system/blob/main/backend/app/services/llm/ollama.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_auth_ui,node_api_client,node_dashboard,node_document_ui,node_analysis_panels,node_chat_panel,node_compare_ui,node_user toneBlue
class node_fastapi,node_api_router,node_auth_api,node_document_api,node_chat_api,node_analysis_api,node_compare_api toneAmber
class node_ingestion,node_extraction,node_chunking,node_retrieval,node_chat_service,node_summary_service,node_terms_service,node_clauses_service,node_compare_service toneMint
class node_database,node_models,node_file_storage toneRose
class node_provider_layer,node_zai,node_ollama toneIndigo
```

## Components

### Web application

- [App routing](https://github.com/devantaris/ai-legal-document-intelligence-system/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Auth state](https://github.com/devantaris/ai-legal-document-intelligence-system/blob/main/frontend/src/stores/auth.ts): `frontend/src/stores/auth.ts`
- [API client](https://github.com/devantaris/ai-legal-document-intelligence-system/blob/main/frontend/src/lib/api.ts): `frontend/src/lib/api.ts`
- [Document dashboard](https://github.com/devantaris/ai-legal-document-intelligence-system/blob/main/frontend/src/pages/DashboardPage.tsx): `frontend/src/pages/DashboardPage.tsx`
- [Document workspace](https://github.com/devantaris/ai-legal-document-intelligence-system/blob/main/frontend/src/pages/DocumentPage.tsx): `frontend/src/pages/DocumentPage.tsx`
- [Analysis panels](https://github.com/devantaris/ai-legal-document-intelligence-system/blob/main/frontend/src/components/SummaryPanel.tsx): `frontend/src/components/SummaryPanel.tsx`
- [Chat panel](https://github.com/devantaris/ai-legal-document-intelligence-system/blob/main/frontend/src/components/ChatPanel.tsx): `frontend/src/components/ChatPanel.tsx`
- [Compare page](https://github.com/devantaris/ai-legal-document-intelligence-system/blob/main/frontend/src/pages/ComparePage.tsx): `frontend/src/pages/ComparePage.tsx`

### API and access

- [FastAPI application](https://github.com/devantaris/ai-legal-document-intelligence-system/blob/main/backend/app/main.py): `backend/app/main.py`
- [API router](https://github.com/devantaris/ai-legal-document-intelligence-system/blob/main/backend/app/api/router.py): `backend/app/api/router.py`
- [Authentication routes](https://github.com/devantaris/ai-legal-document-intelligence-system/blob/main/backend/app/api/auth.py): `backend/app/api/auth.py`
- [Document routes](https://github.com/devantaris/ai-legal-document-intelligence-system/blob/main/backend/app/api/documents.py): `backend/app/api/documents.py`
- [Chat routes](https://github.com/devantaris/ai-legal-document-intelligence-system/blob/main/backend/app/api/chat.py): `backend/app/api/chat.py`
- [Analysis routes](https://github.com/devantaris/ai-legal-document-intelligence-system/blob/main/backend/app/api/analysis.py): `backend/app/api/analysis.py`
- [Comparison routes](https://github.com/devantaris/ai-legal-document-intelligence-system/blob/main/backend/app/api/compare.py): `backend/app/api/compare.py`

### Document intelligence

- [Ingestion orchestrator](https://github.com/devantaris/ai-legal-document-intelligence-system/blob/main/backend/app/services/ingestion.py): `backend/app/services/ingestion.py`
- [Text extraction](https://github.com/devantaris/ai-legal-document-intelligence-system/blob/main/backend/app/services/extraction.py): `backend/app/services/extraction.py`
- [Structure-aware chunking](https://github.com/devantaris/ai-legal-document-intelligence-system/blob/main/backend/app/services/chunking.py): `backend/app/services/chunking.py`
- [Hybrid retrieval](https://github.com/devantaris/ai-legal-document-intelligence-system/blob/main/backend/app/services/retrieval.py): `backend/app/services/retrieval.py`
- [RAG chat](https://github.com/devantaris/ai-legal-document-intelligence-system/blob/main/backend/app/services/chat.py): `backend/app/services/chat.py`
- [Summarization](https://github.com/devantaris/ai-legal-document-intelligence-system/blob/main/backend/app/services/summarization.py): `backend/app/services/summarization.py`
- [Key-term extraction](https://github.com/devantaris/ai-legal-document-intelligence-system/blob/main/backend/app/services/key_terms.py): `backend/app/services/key_terms.py`
- [Clause classification](https://github.com/devantaris/ai-legal-document-intelligence-system/blob/main/backend/app/services/clauses.py): `backend/app/services/clauses.py`
- [Clause comparison](https://github.com/devantaris/ai-legal-document-intelligence-system/blob/main/backend/app/services/compare.py): `backend/app/services/compare.py`

### Persistence and models

- [PostgreSQL and pgvector](https://github.com/devantaris/ai-legal-document-intelligence-system/blob/main/backend/app/core/database.py): `backend/app/core/database.py`
- [Domain models](https://github.com/devantaris/ai-legal-document-intelligence-system/tree/main/backend/app/models): `backend/app/models`
- **Uploaded files**

### LLM providers

- [Provider selection](https://github.com/devantaris/ai-legal-document-intelligence-system/blob/main/backend/app/services/llm/__init__.py): `backend/app/services/llm/__init__.py`
- [Z.ai provider](https://github.com/devantaris/ai-legal-document-intelligence-system/blob/main/backend/app/services/llm/zai.py): `backend/app/services/llm/zai.py`
- [Ollama provider](https://github.com/devantaris/ai-legal-document-intelligence-system/blob/main/backend/app/services/llm/ollama.py): `backend/app/services/llm/ollama.py`

### Other components

- **User**

## Connections

- User → App routing: uses
- App routing → Auth state: checks session (evidence: `frontend/src/App.tsx`)
- App routing → Document dashboard: routes to (evidence: `frontend/src/App.tsx`)
- App routing → Document workspace: routes to (evidence: `frontend/src/App.tsx`)
- App routing → Compare page: routes to (evidence: `frontend/src/App.tsx`)
- Auth state → API client: requests auth (evidence: `frontend/src/stores/auth.ts`)
- Document dashboard → API client: requests documents (evidence: `frontend/src/pages/DashboardPage.tsx`)
- Document workspace → Analysis panels: renders (evidence: `frontend/src/pages/DocumentPage.tsx`)
- Document workspace → Chat panel: renders (evidence: `frontend/src/pages/DocumentPage.tsx`)
- Document workspace → API client: requests analysis (evidence: `frontend/src/pages/DocumentPage.tsx`)
- Compare page → API client: requests comparison (evidence: `frontend/src/pages/ComparePage.tsx`)
- API client → FastAPI application: sends HTTP and SSE
- FastAPI application → API router: mounts routes (evidence: `backend/app/main.py`)
- API router → Authentication routes: registers (evidence: `backend/app/api/router.py`)
- API router → Document routes: registers (evidence: `backend/app/api/router.py`)
- API router → Chat routes: registers (evidence: `backend/app/api/router.py`)
- API router → Analysis routes: registers (evidence: `backend/app/api/router.py`)
- API router → Comparison routes: registers (evidence: `backend/app/api/router.py`)
- Document routes → Ingestion orchestrator: starts processing (evidence: `backend/app/api/documents.py`)
- Document routes → Uploaded files: stores upload
- Ingestion orchestrator → Text extraction: extracts pages (evidence: `backend/app/services/ingestion.py`)
- Ingestion orchestrator → Structure-aware chunking: builds chunks (evidence: `backend/app/services/ingestion.py`)
- Ingestion orchestrator → Provider selection: embeds chunks (evidence: `backend/app/services/ingestion.py`)
- Ingestion orchestrator → PostgreSQL and pgvector: writes chunks and status (evidence: `backend/app/services/ingestion.py`)
- Document routes → PostgreSQL and pgvector: persists document (evidence: `backend/app/api/documents.py`)
- Chat routes → RAG chat: delegates chat (evidence: `backend/app/api/chat.py`)
- RAG chat → Hybrid retrieval: retrieves context
- Hybrid retrieval → PostgreSQL and pgvector: searches chunks
- Hybrid retrieval → Provider selection: embeds query (evidence: `backend/app/services/retrieval.py`)
- RAG chat → Provider selection: generates answer
- Analysis routes → Summarization: requests summary (evidence: `backend/app/api/analysis.py`)
- Analysis routes → Key-term extraction: extracts terms (evidence: `backend/app/api/analysis.py`)
- Analysis routes → Clause classification: lists clauses (evidence: `backend/app/api/analysis.py`)
- Comparison routes → Clause comparison: compares documents (evidence: `backend/app/api/compare.py`)
- Summarization → Provider selection: uses LLM
- Key-term extraction → Provider selection: uses LLM
- Clause classification → Provider selection: uses LLM
- Clause comparison → Provider selection: uses LLM
- Analysis routes → PostgreSQL and pgvector: reads and stores results (evidence: `backend/app/api/analysis.py`)
- Comparison routes → PostgreSQL and pgvector: reads clauses (evidence: `backend/app/api/compare.py`)
- PostgreSQL and pgvector → Domain models: maps domain records (evidence: `backend/app/models/__init__.py`)
- Provider selection → Z.ai provider: selects by config (evidence: `backend/app/services/llm/__init__.py`)
- Provider selection → Ollama provider: selects by config (evidence: `backend/app/services/llm/__init__.py`)
