# adithya880/contractrisk-ai architecture

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

- Interactive diagram: https://gitdiagram.com/adithya880/contractrisk-ai
- Repository: https://github.com/adithya880/contractrisk-ai

## Overview

ContractRisk AI is a contract-review prototype. Its main workflow takes a PDF or DOCX through extraction and clause segmentation, then combines clause classification, rule-based hazard detection, semantic precedent retrieval, and local-LLM reasoning into risk scores and conditional future scenarios. The FastAPI service exposes analysis to a Streamlit upload, progress, and results workflow; PostgreSQL stores completed analyses. The README documents the broad pipeline; sampled source confirms several orchestration and persistence relationships, but not every runtime connection.

Main entry points: [`frontend/app.py`](https://github.com/adithya880/contractrisk-ai/blob/main/frontend/app.py) (Streamlit workflow), [`src/risk_analysis/analyzer.py`](https://github.com/adithya880/contractrisk-ai/blob/main/src/risk_analysis/analyzer.py) (Hybrid risk analysis), [`src/clause_segmentation/segmenter.py`](https://github.com/adithya880/contractrisk-ai/blob/main/src/clause_segmentation/segmenter.py) (Clause segmentation), [`src/api/routes/analysis.py`](https://github.com/adithya880/contractrisk-ai/blob/main/src/api/routes/analysis.py) (Analysis endpoint)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["User workflow"]
  node_streamlit["Streamlit workflow<br/>[app.py]"]
  node_upload["Contract upload"]
  node_results["Results inspection<br/>[results_view.py]"]
end

subgraph group_service["API service"]
  node_api["FastAPI service<br/>[main.py]"]
  node_analysis_route["Analysis endpoint<br/>[analysis.py]"]
end

subgraph group_processing["Document preparation"]
  node_document_loader["Document extraction<br/>[loader.py]"]
  node_clause_segmenter["Clause segmentation<br/>[segmenter.py]"]
end

subgraph group_analysis["Risk intelligence"]
  node_bert["BERT classification<br/>[bert_classifier.py]"]
  node_rule_engine["Regex hazard detection<br/>[rule_engine.py]"]
  node_embedder["Clause embeddings<br/>[embedder.py]"]
  node_vector_index[("FAISS precedent index<br/>[index.py]")]
  node_rag["RAG reasoning<br/>[pipeline.py]"]
  node_llm["Local LLM generation<br/>[generator.py]"]
  node_risk_analyzer["Hybrid risk analysis<br/>[analyzer.py]"]
  node_scoring["Hybrid risk scoring<br/>[scoring.py]"]
  node_scenarios["Scenario prediction"]
end

subgraph group_persistence["Persistence"]
  node_postgres[("PostgreSQL records<br/>[repositories.py]")]
end

node_reviewer(("Contract reviewer"))

node_reviewer -->|"starts review"| node_streamlit
node_streamlit -->|"offers upload"| node_upload
node_streamlit -->|"submits analysis"| node_api
node_api -->|"routes requests"| node_analysis_route
node_analysis_route -->|"loads contract"| node_document_loader
node_document_loader -->|"provides extracted document"| node_clause_segmenter
node_clause_segmenter -->|"segments classified"| node_bert
node_clause_segmenter -->|"segments scanned"| node_rule_engine
node_clause_segmenter -->|"clauses embedded"| node_embedder
node_embedder -->|"builds vectors"| node_vector_index
node_vector_index -->|"supplies precedents"| node_rag
node_rag -->|"generates explanations"| node_llm
node_bert -->|"classification input"| node_risk_analyzer
node_rule_engine -->|"rule matches"| node_risk_analyzer
node_rag -->|"retrieval evidence"| node_risk_analyzer
node_risk_analyzer -->|"aggregates factors"| node_scoring
node_risk_analyzer -->|"predicts consequences"| node_scenarios
node_scenarios -->|"requests generation"| node_llm
node_analysis_route -->|"persists results"| node_postgres
node_api -->|"returns analysis"| node_streamlit
node_streamlit -->|"renders results"| node_results
node_postgres -->|"serves stored records"| node_analysis_route

click node_streamlit "https://github.com/adithya880/contractrisk-ai/blob/main/frontend/app.py"
click node_upload "https://github.com/adithya880/contractrisk-ai/blob/main/frontend/components/contract_uploader.py"
click node_results "https://github.com/adithya880/contractrisk-ai/blob/main/frontend/components/results_view.py"
click node_api "https://github.com/adithya880/contractrisk-ai/blob/main/src/api/main.py"
click node_analysis_route "https://github.com/adithya880/contractrisk-ai/blob/main/src/api/routes/analysis.py"
click node_document_loader "https://github.com/adithya880/contractrisk-ai/blob/main/src/document_processing/loader.py"
click node_clause_segmenter "https://github.com/adithya880/contractrisk-ai/blob/main/src/clause_segmentation/segmenter.py"
click node_bert "https://github.com/adithya880/contractrisk-ai/blob/main/src/models/bert_classifier.py"
click node_rule_engine "https://github.com/adithya880/contractrisk-ai/blob/main/src/risk_analysis/rule_engine.py"
click node_embedder "https://github.com/adithya880/contractrisk-ai/blob/main/src/embeddings/embedder.py"
click node_vector_index "https://github.com/adithya880/contractrisk-ai/blob/main/src/embeddings/index.py"
click node_rag "https://github.com/adithya880/contractrisk-ai/blob/main/src/rag/pipeline.py"
click node_llm "https://github.com/adithya880/contractrisk-ai/blob/main/src/rag/generator.py"
click node_risk_analyzer "https://github.com/adithya880/contractrisk-ai/blob/main/src/risk_analysis/analyzer.py"
click node_scoring "https://github.com/adithya880/contractrisk-ai/blob/main/src/risk_analysis/scoring.py"
click node_scenarios "https://github.com/adithya880/contractrisk-ai/blob/main/src/risk_analysis/scenario_predictor.py"
click node_postgres "https://github.com/adithya880/contractrisk-ai/blob/main/src/database/repositories.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_streamlit,node_upload,node_results,node_reviewer toneBlue
class node_api,node_analysis_route toneAmber
class node_document_loader,node_clause_segmenter toneMint
class node_bert,node_rule_engine,node_embedder,node_vector_index,node_rag,node_llm,node_risk_analyzer,node_scoring,node_scenarios toneRose
class node_postgres toneIndigo
```

## Components

### User workflow

- [Streamlit workflow](https://github.com/adithya880/contractrisk-ai/blob/main/frontend/app.py): `frontend/app.py`
- [Contract upload](https://github.com/adithya880/contractrisk-ai/blob/main/frontend/components/contract_uploader.py): `frontend/components/contract_uploader.py`
- [Results inspection](https://github.com/adithya880/contractrisk-ai/blob/main/frontend/components/results_view.py): `frontend/components/results_view.py`

### API service

- [FastAPI service](https://github.com/adithya880/contractrisk-ai/blob/main/src/api/main.py): `src/api/main.py`
- [Analysis endpoint](https://github.com/adithya880/contractrisk-ai/blob/main/src/api/routes/analysis.py): `src/api/routes/analysis.py`

### Document preparation

- [Document extraction](https://github.com/adithya880/contractrisk-ai/blob/main/src/document_processing/loader.py): `src/document_processing/loader.py`
- [Clause segmentation](https://github.com/adithya880/contractrisk-ai/blob/main/src/clause_segmentation/segmenter.py): `src/clause_segmentation/segmenter.py`

### Risk intelligence

- [BERT classification](https://github.com/adithya880/contractrisk-ai/blob/main/src/models/bert_classifier.py): `src/models/bert_classifier.py`
- [Regex hazard detection](https://github.com/adithya880/contractrisk-ai/blob/main/src/risk_analysis/rule_engine.py): `src/risk_analysis/rule_engine.py`
- [Clause embeddings](https://github.com/adithya880/contractrisk-ai/blob/main/src/embeddings/embedder.py): `src/embeddings/embedder.py`
- [FAISS precedent index](https://github.com/adithya880/contractrisk-ai/blob/main/src/embeddings/index.py): `src/embeddings/index.py`
- [RAG reasoning](https://github.com/adithya880/contractrisk-ai/blob/main/src/rag/pipeline.py): `src/rag/pipeline.py`
- [Local LLM generation](https://github.com/adithya880/contractrisk-ai/blob/main/src/rag/generator.py): `src/rag/generator.py`
- [Hybrid risk analysis](https://github.com/adithya880/contractrisk-ai/blob/main/src/risk_analysis/analyzer.py): `src/risk_analysis/analyzer.py`
- [Hybrid risk scoring](https://github.com/adithya880/contractrisk-ai/blob/main/src/risk_analysis/scoring.py): `src/risk_analysis/scoring.py`
- [Scenario prediction](https://github.com/adithya880/contractrisk-ai/blob/main/src/risk_analysis/scenario_predictor.py): `src/risk_analysis/scenario_predictor.py`

### Persistence

- [PostgreSQL records](https://github.com/adithya880/contractrisk-ai/blob/main/src/database/repositories.py): `src/database/repositories.py`

### Other components

- **Contract reviewer**

## Connections

- Contract reviewer → Streamlit workflow: starts review (evidence: `README.md`)
- Streamlit workflow → Contract upload: offers upload (evidence: `README.md`)
- Streamlit workflow → FastAPI service: submits analysis (evidence: `README.md`)
- FastAPI service → Analysis endpoint: routes requests (evidence: `src/api/main.py`)
- Analysis endpoint → Document extraction: loads contract (evidence: `src/api/routes/analysis.py`)
- Document extraction → Clause segmentation: provides extracted document (evidence: `src/clause_segmentation/segmenter.py`)
- Clause segmentation → BERT classification: segments classified (evidence: `README.md`)
- Clause segmentation → Regex hazard detection: segments scanned (evidence: `README.md`)
- Clause segmentation → Clause embeddings: clauses embedded (evidence: `README.md`)
- Clause embeddings → FAISS precedent index: builds vectors (evidence: `src/embeddings/index.py`)
- FAISS precedent index → RAG reasoning: supplies precedents (evidence: `README.md`)
- RAG reasoning → Local LLM generation: generates explanations (evidence: `src/rag/pipeline.py`)
- BERT classification → Hybrid risk analysis: classification input (evidence: `README.md`)
- Regex hazard detection → Hybrid risk analysis: rule matches (evidence: `src/risk_analysis/analyzer.py`)
- RAG reasoning → Hybrid risk analysis: retrieval evidence (evidence: `src/risk_analysis/analyzer.py`)
- Hybrid risk analysis → Hybrid risk scoring: aggregates factors (evidence: `README.md`)
- Hybrid risk analysis → Scenario prediction: predicts consequences (evidence: `src/risk_analysis/analyzer.py`)
- Scenario prediction → Local LLM generation: requests generation (evidence: `src/risk_analysis/scenario_predictor.py`)
- Analysis endpoint → PostgreSQL records: persists results (evidence: `src/api/routes/analysis.py`)
- FastAPI service → Streamlit workflow: returns analysis (evidence: `README.md`)
- Streamlit workflow → Results inspection: renders results (evidence: `frontend/app.py`)
- PostgreSQL records → Analysis endpoint: serves stored records (evidence: `src/api/routes/analysis.py`)
