# omar9965/legal-assistant architecture

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

- Interactive diagram: https://gitdiagram.com/omar9965/legal-assistant
- Repository: https://github.com/omar9965/legal-assistant

## Overview

This is a bilingual Egyptian Civil Code legal assistant: users submit questions through Streamlit, which invokes a LangGraph workflow for heuristic routing, confidence-gated caching, legal retrieval (including reformulation retries), and answer synthesis with conversation history. A separate ingestion path parses and chunks legal PDFs into the searchable collection and invalidates cached answers. The map preserves documented bilingual, caching, retrieval, and ingestion capabilities; unsampled implementation details and unverified connections are omitted.

Main entry points: [`controllers/graph_nodes.py`](https://github.com/omar9965/legal-assistant/blob/master/controllers/graph_nodes.py) (Workflow Nodes), [`controllers/graph.py`](https://github.com/omar9965/legal-assistant/blob/master/controllers/graph.py) (Workflow Graph), [`controllers/researcher.py`](https://github.com/omar9965/legal-assistant/blob/master/controllers/researcher.py) (Research Agent), [`models/vector_store.py`](https://github.com/omar9965/legal-assistant/blob/master/models/vector_store.py) (Vector Store)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["User Interface"]
  node_app["App Entry<br/>[app.py]"]
  node_chat_ui["Chat UI<br/>[streamlit_app.py]"]
end

subgraph group_workflow["Agent Workflow"]
  node_graph["Workflow Graph<br/>[graph.py]"]
  node_graph_nodes["Workflow Nodes<br/>[graph_nodes.py]"]
  node_graph_edges["Workflow Routing<br/>[graph_edges.py]"]
  node_graph_state["Workflow State<br/>[graph_state.py]"]
  node_router["Query Router<br/>[router.py]"]
  node_cache_agent["Cache Agent<br/>[graph_nodes.py]"]
  node_scribe["Answer Synthesis<br/>[scribe.py]"]
end

subgraph group_retrieval["Legal Retrieval"]
  node_research_agent["Research Agent<br/>[researcher.py]"]
  node_reformulator["Query Reformulation<br/>[graph_nodes.py]"]
  node_expansion["Query Expansion<br/>[query_expansion.py]"]
  node_relevance["Relevance Scoring"]
  node_article_parser["Article Extraction"]
end

subgraph group_data["Models and Storage"]
  node_resources["Model Resources<br/>[resources.py]"]
  node_vector_store["Vector Store<br/>[vector_store.py]"]
  node_legal_collection[("Legal Collection")]
  node_response_cache["Response Cache<br/>[cache.py]"]
  node_semantic_collection[("Semantic Cache")]
  node_config["Runtime Config<br/>[config.py]"]
end

subgraph group_ingestion["Document Ingestion"]
  node_ingestion["Ingestion Pipeline<br/>[process.py]"]
  node_pdf_processor["PDF Processing"]
end

node_user(("Legal User"))
node_pdfs["Legal PDFs"]
node_llm["LLM Endpoint"]

node_user -->|"submits query"| node_chat_ui
node_app -->|"routes to"| node_chat_ui
node_chat_ui -->|"runs query"| node_graph
node_graph -->|"registers nodes"| node_graph_nodes
node_graph -->|"uses routing"| node_graph_edges
node_graph -->|"uses state"| node_graph_state
node_graph -->|"invalidates cache"| node_response_cache
node_graph_nodes -->|"classifies query"| node_router
node_graph_nodes -->|"checks cache"| node_cache_agent
node_graph_nodes -->|"retrieves documents"| node_research_agent
node_graph_nodes -->|"retries search"| node_reformulator
node_graph_nodes -->|"synthesizes answer"| node_scribe
node_research_agent -->|"searches collection"| node_vector_store
node_research_agent -->|"expands query"| node_expansion
node_research_agent -->|"scores results"| node_relevance
node_research_agent -->|"extracts article"| node_article_parser
node_reformulator -->|"uses synonyms"| node_expansion
node_vector_store -->|"reads and writes"| node_legal_collection
node_response_cache -->|"reads and writes"| node_semantic_collection
node_scribe -->|"gets LLM"| node_resources
node_resources -->|"configures client"| node_llm
node_vector_store -->|"gets embeddings"| node_resources
node_ingestion -->|"processes PDFs"| node_pdf_processor
node_ingestion -->|"indexes chunks"| node_vector_store
node_ingestion -->|"invalidates cache"| node_response_cache
node_pdfs -->|"provides source files"| node_ingestion
node_config -->|"configures storage"| node_vector_store
node_config -->|"configures models"| node_resources

click node_app "https://github.com/omar9965/legal-assistant/blob/master/app.py"
click node_chat_ui "https://github.com/omar9965/legal-assistant/blob/master/views/streamlit_app.py"
click node_graph "https://github.com/omar9965/legal-assistant/blob/master/controllers/graph.py"
click node_graph_nodes "https://github.com/omar9965/legal-assistant/blob/master/controllers/graph_nodes.py"
click node_graph_edges "https://github.com/omar9965/legal-assistant/blob/master/controllers/graph_edges.py"
click node_graph_state "https://github.com/omar9965/legal-assistant/blob/master/controllers/graph_state.py"
click node_router "https://github.com/omar9965/legal-assistant/blob/master/controllers/router.py"
click node_cache_agent "https://github.com/omar9965/legal-assistant/blob/master/controllers/graph_nodes.py"
click node_research_agent "https://github.com/omar9965/legal-assistant/blob/master/controllers/researcher.py"
click node_reformulator "https://github.com/omar9965/legal-assistant/blob/master/controllers/graph_nodes.py"
click node_expansion "https://github.com/omar9965/legal-assistant/blob/master/models/query_expansion.py"
click node_relevance "https://github.com/omar9965/legal-assistant/blob/master/models/metadata_filtering.py"
click node_article_parser "https://github.com/omar9965/legal-assistant/blob/master/models/document_processor.py"
click node_scribe "https://github.com/omar9965/legal-assistant/blob/master/controllers/scribe.py"
click node_resources "https://github.com/omar9965/legal-assistant/blob/master/models/resources.py"
click node_vector_store "https://github.com/omar9965/legal-assistant/blob/master/models/vector_store.py"
click node_response_cache "https://github.com/omar9965/legal-assistant/blob/master/models/cache.py"
click node_config "https://github.com/omar9965/legal-assistant/blob/master/utils/config.py"
click node_ingestion "https://github.com/omar9965/legal-assistant/blob/master/process.py"
click node_pdf_processor "https://github.com/omar9965/legal-assistant/blob/master/models/document_processor.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_chat_ui,node_user toneBlue
class node_graph,node_graph_nodes,node_graph_edges,node_graph_state,node_router,node_cache_agent,node_scribe toneAmber
class node_research_agent,node_reformulator,node_expansion,node_relevance,node_article_parser toneMint
class node_resources,node_vector_store,node_legal_collection,node_response_cache,node_semantic_collection,node_config toneRose
class node_ingestion,node_pdf_processor,node_pdfs,node_llm toneIndigo
```

## Components

### User Interface

- [App Entry](https://github.com/omar9965/legal-assistant/blob/master/app.py): `app.py`
- [Chat UI](https://github.com/omar9965/legal-assistant/blob/master/views/streamlit_app.py): `views/streamlit_app.py`

### Agent Workflow

- [Workflow Graph](https://github.com/omar9965/legal-assistant/blob/master/controllers/graph.py): `controllers/graph.py`
- [Workflow Nodes](https://github.com/omar9965/legal-assistant/blob/master/controllers/graph_nodes.py): `controllers/graph_nodes.py`
- [Workflow Routing](https://github.com/omar9965/legal-assistant/blob/master/controllers/graph_edges.py): `controllers/graph_edges.py`
- [Workflow State](https://github.com/omar9965/legal-assistant/blob/master/controllers/graph_state.py): `controllers/graph_state.py`
- [Query Router](https://github.com/omar9965/legal-assistant/blob/master/controllers/router.py): `controllers/router.py`
- [Cache Agent](https://github.com/omar9965/legal-assistant/blob/master/controllers/graph_nodes.py): `controllers/graph_nodes.py`
- [Answer Synthesis](https://github.com/omar9965/legal-assistant/blob/master/controllers/scribe.py): `controllers/scribe.py`

### Legal Retrieval

- [Research Agent](https://github.com/omar9965/legal-assistant/blob/master/controllers/researcher.py): `controllers/researcher.py`
- [Query Reformulation](https://github.com/omar9965/legal-assistant/blob/master/controllers/graph_nodes.py): `controllers/graph_nodes.py`
- [Query Expansion](https://github.com/omar9965/legal-assistant/blob/master/models/query_expansion.py): `models/query_expansion.py`
- [Relevance Scoring](https://github.com/omar9965/legal-assistant/blob/master/models/metadata_filtering.py): `models/metadata_filtering.py`
- [Article Extraction](https://github.com/omar9965/legal-assistant/blob/master/models/document_processor.py): `models/document_processor.py`

### Models and Storage

- [Model Resources](https://github.com/omar9965/legal-assistant/blob/master/models/resources.py): `models/resources.py`
- [Vector Store](https://github.com/omar9965/legal-assistant/blob/master/models/vector_store.py): `models/vector_store.py`
- **Legal Collection**
- [Response Cache](https://github.com/omar9965/legal-assistant/blob/master/models/cache.py): `models/cache.py`
- **Semantic Cache**
- [Runtime Config](https://github.com/omar9965/legal-assistant/blob/master/utils/config.py): `utils/config.py`

### Document Ingestion

- [Ingestion Pipeline](https://github.com/omar9965/legal-assistant/blob/master/process.py): `process.py`
- [PDF Processing](https://github.com/omar9965/legal-assistant/blob/master/models/document_processor.py): `models/document_processor.py`

### Other components

- **Legal User**
- **Legal PDFs**
- **LLM Endpoint**

## Connections

- Legal User → Chat UI: submits query (evidence: `README.md`)
- App Entry → Chat UI: routes to (evidence: `README.md`)
- Chat UI → Workflow Graph: runs query (evidence: `views/streamlit_app.py`)
- Workflow Graph → Workflow Nodes: registers nodes (evidence: `controllers/graph.py`)
- Workflow Graph → Workflow Routing: uses routing (evidence: `controllers/graph.py`)
- Workflow Graph → Workflow State: uses state (evidence: `controllers/graph.py`)
- Workflow Graph → Response Cache: invalidates cache (evidence: `controllers/graph.py`)
- Workflow Nodes → Query Router: classifies query (evidence: `controllers/graph_nodes.py`)
- Workflow Nodes → Cache Agent: checks cache (evidence: `controllers/graph_nodes.py`)
- Workflow Nodes → Research Agent: retrieves documents (evidence: `controllers/graph_nodes.py`)
- Workflow Nodes → Query Reformulation: retries search (evidence: `controllers/graph_nodes.py`)
- Workflow Nodes → Answer Synthesis: synthesizes answer (evidence: `controllers/graph_nodes.py`)
- Research Agent → Vector Store: searches collection (evidence: `controllers/researcher.py`)
- Research Agent → Query Expansion: expands query (evidence: `controllers/researcher.py`)
- Research Agent → Relevance Scoring: scores results (evidence: `controllers/researcher.py`)
- Research Agent → Article Extraction: extracts article (evidence: `controllers/researcher.py`)
- Query Reformulation → Query Expansion: uses synonyms (evidence: `controllers/graph_nodes.py`)
- Vector Store → Legal Collection: reads and writes (evidence: `models/vector_store.py`)
- Response Cache → Semantic Cache: reads and writes (evidence: `models/cache.py`)
- Answer Synthesis → Model Resources: gets LLM (evidence: `controllers/scribe.py`)
- Model Resources → LLM Endpoint: configures client (evidence: `models/resources.py`)
- Vector Store → Model Resources: gets embeddings (evidence: `models/vector_store.py`)
- Ingestion Pipeline → PDF Processing: processes PDFs (evidence: `process.py`)
- Ingestion Pipeline → Vector Store: indexes chunks (evidence: `process.py`)
- Ingestion Pipeline → Response Cache: invalidates cache (evidence: `process.py`)
- Legal PDFs → Ingestion Pipeline: provides source files (evidence: `README.md`)
- Runtime Config → Vector Store: configures storage (evidence: `models/vector_store.py`)
- Runtime Config → Model Resources: configures models (evidence: `models/resources.py`)
