# mohammedakramosama/smart-contract-rag-assistant architecture

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

- Interactive diagram: https://gitdiagram.com/mohammedakramosama/smart-contract-rag-assistant
- Repository: https://github.com/mohammedakramosama/smart-contract-rag-assistant

## Overview

Smart Contract Assistant is a document-grounded contract analysis application. Users upload a contract, which the API ingests into a searchable vector store; they can then ask questions or request a structured summary, with chat answers guarded and cited. The Gradio UI is documented as a separate frontend, but its API calls are not visible in the sampled source, so that relationship is shown as unverified. Evaluation and health checks are separate capabilities. Unsampled utility modules are included where the source index identifies them, without assuming they are wired into the main pipeline.

Main entry points: [`app/core/llm.py`](https://github.com/mohammedakramosama/smart-contract-rag-assistant/blob/main/app/core/llm.py) (Model factories), [`app/pipelines/retrieval.py`](https://github.com/mohammedakramosama/smart-contract-rag-assistant/blob/main/app/pipelines/retrieval.py) (RAG retrieval), [`app/main.py`](https://github.com/mohammedakramosama/smart-contract-rag-assistant/blob/main/app/main.py) (FastAPI application), [`app/api/routes_chat.py`](https://github.com/mohammedakramosama/smart-contract-rag-assistant/blob/main/app/api/routes_chat.py) (Chat and reset)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User interfaces"]
  node_gradio["Gradio UI<br/>[gradio_app.py]"]
end

subgraph group_api["API routing"]
  node_apiapp["FastAPI application<br/>[main.py]"]
  node_health["Health endpoint<br/>[routes_health.py]"]
  node_upload["Upload endpoint<br/>[routes_upload.py]"]
  node_chat["Chat and reset<br/>[routes_chat.py]"]
end

subgraph group_documents["Document indexing"]
  node_ingest["PDF ingestion<br/>[ingestion.py]"]
  node_fileparse["Document parsers<br/>[file_parsers.py]"]
  node_splitter["Text splitting<br/>[text_splitter.py]"]
  node_vectors[("Chroma vector store<br/>[ingestion.py]")]
end

subgraph group_analysis["Contract analysis"]
  node_retrieve["RAG retrieval<br/>[retrieval.py]"]
  node_summarize["Contract summary<br/>[summarization.py]"]
  node_evaluation["Response evaluation<br/>[evaluation.py]"]
  node_guardrails["Answer guardrails<br/>[guardrails.py]"]
  node_citations["Citation formatting<br/>[citations.py]"]
end

subgraph group_platform["Models and operations"]
  node_llmfactory["Model factories<br/>[llm.py]"]
  node_config["Settings<br/>[config.py]"]
  node_logging["Logging<br/>[logging.py]"]
end

node_user(("Contract user"))
node_gemini{{"Gemini"}}
node_ollama{{"Ollama embeddings"}}
node_analyst(("Evaluation caller"))

node_user -->|"uses"| node_gradio
node_user -->|"calls API"| node_apiapp
node_gradio -.->|"API calls"| node_apiapp
node_apiapp -->|"mounts routes"| node_health
node_apiapp -->|"mounts routes"| node_upload
node_apiapp -->|"mounts routes"| node_chat
node_upload -->|"ingests file"| node_ingest
node_ingest -->|"writes chunks"| node_vectors
node_ingest -->|"gets embeddings"| node_llmfactory
node_llmfactory -->|"creates embeddings"| node_ollama
node_chat -->|"answers questions"| node_retrieve
node_chat -->|"requests summary"| node_summarize
node_retrieve -->|"searches chunks"| node_vectors
node_retrieve -->|"checks answers"| node_guardrails
node_retrieve -->|"formats sources"| node_citations
node_retrieve -->|"gets model"| node_llmfactory
node_summarize -->|"searches excerpts"| node_vectors
node_summarize -->|"gets model"| node_llmfactory
node_llmfactory -->|"creates chat model"| node_gemini
node_llmfactory -->|"reads settings"| node_config
node_health -->|"reads settings"| node_config
node_analyst -->|"evaluates response"| node_evaluation
node_evaluation -->|"uses model"| node_llmfactory
node_analyst -.->|"uses parser"| node_fileparse
node_analyst -.->|"uses splitter"| node_splitter

click node_gradio "https://github.com/mohammedakramosama/smart-contract-rag-assistant/blob/main/frontend/gradio_app.py"
click node_apiapp "https://github.com/mohammedakramosama/smart-contract-rag-assistant/blob/main/app/main.py"
click node_health "https://github.com/mohammedakramosama/smart-contract-rag-assistant/blob/main/app/api/routes_health.py"
click node_upload "https://github.com/mohammedakramosama/smart-contract-rag-assistant/blob/main/app/api/routes_upload.py"
click node_chat "https://github.com/mohammedakramosama/smart-contract-rag-assistant/blob/main/app/api/routes_chat.py"
click node_ingest "https://github.com/mohammedakramosama/smart-contract-rag-assistant/blob/main/app/pipelines/ingestion.py"
click node_fileparse "https://github.com/mohammedakramosama/smart-contract-rag-assistant/blob/main/app/utils/file_parsers.py"
click node_splitter "https://github.com/mohammedakramosama/smart-contract-rag-assistant/blob/main/app/utils/text_splitter.py"
click node_vectors "https://github.com/mohammedakramosama/smart-contract-rag-assistant/blob/main/app/pipelines/ingestion.py"
click node_retrieve "https://github.com/mohammedakramosama/smart-contract-rag-assistant/blob/main/app/pipelines/retrieval.py"
click node_summarize "https://github.com/mohammedakramosama/smart-contract-rag-assistant/blob/main/app/pipelines/summarization.py"
click node_evaluation "https://github.com/mohammedakramosama/smart-contract-rag-assistant/blob/main/app/pipelines/evaluation.py"
click node_guardrails "https://github.com/mohammedakramosama/smart-contract-rag-assistant/blob/main/app/utils/guardrails.py"
click node_citations "https://github.com/mohammedakramosama/smart-contract-rag-assistant/blob/main/app/utils/citations.py"
click node_llmfactory "https://github.com/mohammedakramosama/smart-contract-rag-assistant/blob/main/app/core/llm.py"
click node_config "https://github.com/mohammedakramosama/smart-contract-rag-assistant/blob/main/app/core/config.py"
click node_logging "https://github.com/mohammedakramosama/smart-contract-rag-assistant/blob/main/app/core/logging.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_gradio,node_user toneBlue
class node_apiapp,node_health,node_upload,node_chat toneAmber
class node_ingest,node_fileparse,node_splitter,node_vectors toneMint
class node_retrieve,node_summarize,node_evaluation,node_guardrails,node_citations toneRose
class node_llmfactory,node_config,node_logging,node_gemini,node_ollama,node_analyst toneIndigo
```

## Components

### User interfaces

- [Gradio UI](https://github.com/mohammedakramosama/smart-contract-rag-assistant/blob/main/frontend/gradio_app.py): `frontend/gradio_app.py`

### API routing

- [FastAPI application](https://github.com/mohammedakramosama/smart-contract-rag-assistant/blob/main/app/main.py): `app/main.py`
- [Health endpoint](https://github.com/mohammedakramosama/smart-contract-rag-assistant/blob/main/app/api/routes_health.py): `app/api/routes_health.py`
- [Upload endpoint](https://github.com/mohammedakramosama/smart-contract-rag-assistant/blob/main/app/api/routes_upload.py): `app/api/routes_upload.py`
- [Chat and reset](https://github.com/mohammedakramosama/smart-contract-rag-assistant/blob/main/app/api/routes_chat.py): `app/api/routes_chat.py`

### Document indexing

- [PDF ingestion](https://github.com/mohammedakramosama/smart-contract-rag-assistant/blob/main/app/pipelines/ingestion.py): `app/pipelines/ingestion.py`
- [Document parsers](https://github.com/mohammedakramosama/smart-contract-rag-assistant/blob/main/app/utils/file_parsers.py): `app/utils/file_parsers.py`
- [Text splitting](https://github.com/mohammedakramosama/smart-contract-rag-assistant/blob/main/app/utils/text_splitter.py): `app/utils/text_splitter.py`
- [Chroma vector store](https://github.com/mohammedakramosama/smart-contract-rag-assistant/blob/main/app/pipelines/ingestion.py): `app/pipelines/ingestion.py`

### Contract analysis

- [RAG retrieval](https://github.com/mohammedakramosama/smart-contract-rag-assistant/blob/main/app/pipelines/retrieval.py): `app/pipelines/retrieval.py`
- [Contract summary](https://github.com/mohammedakramosama/smart-contract-rag-assistant/blob/main/app/pipelines/summarization.py): `app/pipelines/summarization.py`
- [Response evaluation](https://github.com/mohammedakramosama/smart-contract-rag-assistant/blob/main/app/pipelines/evaluation.py): `app/pipelines/evaluation.py`
- [Answer guardrails](https://github.com/mohammedakramosama/smart-contract-rag-assistant/blob/main/app/utils/guardrails.py): `app/utils/guardrails.py`
- [Citation formatting](https://github.com/mohammedakramosama/smart-contract-rag-assistant/blob/main/app/utils/citations.py): `app/utils/citations.py`

### Models and operations

- [Model factories](https://github.com/mohammedakramosama/smart-contract-rag-assistant/blob/main/app/core/llm.py): `app/core/llm.py`
- [Settings](https://github.com/mohammedakramosama/smart-contract-rag-assistant/blob/main/app/core/config.py): `app/core/config.py`
- [Logging](https://github.com/mohammedakramosama/smart-contract-rag-assistant/blob/main/app/core/logging.py): `app/core/logging.py`

### Other components

- **Contract user**
- **Gemini**
- **Ollama embeddings**
- **Evaluation caller**

## Connections

- Contract user → Gradio UI: uses (evidence: `README.md`)
- Contract user → FastAPI application: calls API (evidence: `README.md`)
- Gradio UI → FastAPI application: API calls
- FastAPI application → Health endpoint: mounts routes (evidence: `app/main.py`)
- FastAPI application → Upload endpoint: mounts routes (evidence: `app/main.py`)
- FastAPI application → Chat and reset: mounts routes (evidence: `app/main.py`)
- Upload endpoint → PDF ingestion: ingests file (evidence: `app/api/routes_upload.py`)
- PDF ingestion → Chroma vector store: writes chunks (evidence: `app/pipelines/ingestion.py`)
- PDF ingestion → Model factories: gets embeddings (evidence: `app/pipelines/ingestion.py`)
- Model factories → Ollama embeddings: creates embeddings (evidence: `app/core/llm.py`)
- Chat and reset → RAG retrieval: answers questions (evidence: `app/api/routes_chat.py`)
- Chat and reset → Contract summary: requests summary (evidence: `app/api/routes_chat.py`)
- RAG retrieval → Chroma vector store: searches chunks (evidence: `app/pipelines/retrieval.py`)
- RAG retrieval → Answer guardrails: checks answers (evidence: `app/pipelines/retrieval.py`)
- RAG retrieval → Citation formatting: formats sources (evidence: `app/pipelines/retrieval.py`)
- RAG retrieval → Model factories: gets model (evidence: `app/pipelines/retrieval.py`)
- Contract summary → Chroma vector store: searches excerpts (evidence: `app/pipelines/summarization.py`)
- Contract summary → Model factories: gets model (evidence: `app/pipelines/summarization.py`)
- Model factories → Gemini: creates chat model (evidence: `app/core/llm.py`)
- Model factories → Settings: reads settings (evidence: `app/core/llm.py`)
- Health endpoint → Settings: reads settings (evidence: `app/api/routes_health.py`)
- Evaluation caller → Response evaluation: evaluates response (evidence: `README.md`)
- Response evaluation → Model factories: uses model (evidence: `app/pipelines/evaluation.py`)
- Evaluation caller → Document parsers: uses parser
- Evaluation caller → Text splitting: uses splitter