# anuragbodkhe/contractguard-ai architecture

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

- Interactive diagram: https://gitdiagram.com/anuragbodkhe/contractguard-ai
- Repository: https://github.com/anuragbodkhe/contractguard-ai

## Overview

ContractGuard AI is a contract-analysis product: users upload a contract with contract type, jurisdiction, and party role, then review clause-level predictions, extracted entities, risk findings, and a downloadable report. The documented architecture places Spring Boot between the browser and the ML service; the ML service is not browser-facing. The README supports the main service relationships and capabilities; sampled excerpts also show pipeline degradation behavior and model/API registration, but do not expose every pipeline-stage call.

Main entry points: [`backend/src/main/java/com/contractguard/ContractGuardApplication.java`](https://github.com/anuragbodkhe/contractguard-ai/blob/main/backend/src/main/java/com/contractguard/ContractGuardApplication.java) (Spring API), [`backend/src/main/java/com/contractguard/analysis/AnalysisPipeline.java`](https://github.com/anuragbodkhe/contractguard-ai/blob/main/backend/src/main/java/com/contractguard/analysis/AnalysisPipeline.java) (Analysis orchestration), [`backend/src/main/java/com/contractguard/retrieval/ContractQaService.java`](https://github.com/anuragbodkhe/contractguard-ai/blob/main/backend/src/main/java/com/contractguard/retrieval/ContractQaService.java) (Contract Q&A), [`backend/src/main/java/com/contractguard/ml/client/MlServiceClient.java`](https://github.com/anuragbodkhe/contractguard-ai/blob/main/backend/src/main/java/com/contractguard/ml/client/MlServiceClient.java) (ML service client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_web["Web application<br/>[App.tsx]"]
end

subgraph group_backend["Spring backend"]
  node_api["Spring API"]
  node_auth["Authentication<br/>[AuthService.java]"]
  node_contracts["Contract intake"]
  node_storage["Document storage"]
  node_analysis["Analysis orchestration"]
  node_segmentation["Clause segmentation"]
  node_rules["Rule findings<br/>[RuleEngine.java]"]
  node_risk["Risk aggregation"]
  node_views["Analysis views"]
  node_reports["Report generation<br/>[ReportService.java]"]
  node_qa["Contract Q&amp;A"]
  node_embeddings[("Vector retrieval")]
  node_mlclient["ML service client"]
  node_registry["Model registry"]
  node_explanations["Explanations"]
  node_database[("PostgreSQL")]
end

subgraph group_ml["ML inference"]
  node_mlapi["ML inference API<br/>[main.py]"]
  node_manager["Model manager<br/>[manager.py]"]
  node_models["Five task models"]
end

subgraph group_knowledge["Legal knowledge"]
  node_legal["Legal sources"]
end

node_user(("Contract analyst"))
node_llm["Optional LLM provider"]

node_user -->|"uses"| node_web
node_web -->|"sends requests"| node_api
node_api -.->|"authenticates"| node_auth
node_api -->|"accepts uploads"| node_contracts
node_contracts -->|"stores files"| node_storage
node_api -->|"starts analysis"| node_analysis
node_analysis -.->|"segments clauses"| node_segmentation
node_analysis -->|"requests predictions"| node_mlclient
node_mlclient -->|"calls inference"| node_mlapi
node_mlapi -->|"dispatches inference"| node_manager
node_manager -->|"holds models"| node_models
node_analysis -.->|"evaluates rules"| node_rules
node_analysis -.->|"aggregates risk"| node_risk
node_analysis -->|"persists findings"| node_database
node_api -.->|"serves results"| node_views
node_api -->|"provides reports"| node_reports
node_reports -->|"includes sources"| node_legal
node_api -.->|"offers Q&amp;A"| node_qa
node_qa -->|"retrieves vectors"| node_embeddings
node_qa -->|"requests embeddings"| node_mlclient
node_api -.->|"manages models"| node_registry
node_registry -->|"records versions"| node_database
node_analysis -.->|"builds explanations"| node_explanations
node_explanations -.->|"optionally generates"| node_llm

click node_web "https://github.com/anuragbodkhe/contractguard-ai/blob/main/frontend/src/App.tsx"
click node_api "https://github.com/anuragbodkhe/contractguard-ai/blob/main/backend/src/main/java/com/contractguard/ContractGuardApplication.java"
click node_auth "https://github.com/anuragbodkhe/contractguard-ai/blob/main/backend/src/main/java/com/contractguard/auth/AuthService.java"
click node_contracts "https://github.com/anuragbodkhe/contractguard-ai/blob/main/backend/src/main/java/com/contractguard/contract/ContractService.java"
click node_storage "https://github.com/anuragbodkhe/contractguard-ai/blob/main/backend/src/main/java/com/contractguard/document/StorageService.java"
click node_analysis "https://github.com/anuragbodkhe/contractguard-ai/blob/main/backend/src/main/java/com/contractguard/analysis/AnalysisPipeline.java"
click node_segmentation "https://github.com/anuragbodkhe/contractguard-ai/blob/main/backend/src/main/java/com/contractguard/clause/ClauseSegmentationService.java"
click node_rules "https://github.com/anuragbodkhe/contractguard-ai/blob/main/backend/src/main/java/com/contractguard/ruleengine/RuleEngine.java"
click node_risk "https://github.com/anuragbodkhe/contractguard-ai/blob/main/backend/src/main/java/com/contractguard/risk/RiskAggregationService.java"
click node_views "https://github.com/anuragbodkhe/contractguard-ai/blob/main/backend/src/main/java/com/contractguard/analysis/AnalysisViewService.java"
click node_reports "https://github.com/anuragbodkhe/contractguard-ai/blob/main/backend/src/main/java/com/contractguard/report/ReportService.java"
click node_qa "https://github.com/anuragbodkhe/contractguard-ai/blob/main/backend/src/main/java/com/contractguard/retrieval/ContractQaService.java"
click node_embeddings "https://github.com/anuragbodkhe/contractguard-ai/blob/main/backend/src/main/java/com/contractguard/retrieval/EmbeddingStore.java"
click node_mlclient "https://github.com/anuragbodkhe/contractguard-ai/blob/main/backend/src/main/java/com/contractguard/ml/client/MlServiceClient.java"
click node_registry "https://github.com/anuragbodkhe/contractguard-ai/blob/main/backend/src/main/java/com/contractguard/admin/ModelRegistryService.java"
click node_explanations "https://github.com/anuragbodkhe/contractguard-ai/blob/main/backend/src/main/java/com/contractguard/llm/ExplanationService.java"
click node_legal "https://github.com/anuragbodkhe/contractguard-ai/blob/main/backend/src/main/java/com/contractguard/legalsource/LegalSourceService.java"
click node_mlapi "https://github.com/anuragbodkhe/contractguard-ai/blob/main/ml-service/app/main.py"
click node_manager "https://github.com/anuragbodkhe/contractguard-ai/blob/main/ml-service/app/inference/manager.py"
click node_models "https://github.com/anuragbodkhe/contractguard-ai/tree/main/ml-service/app/models"

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_web toneBlue
class node_api,node_auth,node_contracts,node_storage,node_analysis,node_segmentation,node_rules,node_risk,node_views,node_reports,node_qa,node_embeddings,node_mlclient,node_registry,node_explanations,node_database toneAmber
class node_mlapi,node_manager,node_models toneMint
class node_legal toneRose
class node_user,node_llm toneIndigo
```

## Components

### User experience

- [Web application](https://github.com/anuragbodkhe/contractguard-ai/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`

### Spring backend

- [Spring API](https://github.com/anuragbodkhe/contractguard-ai/blob/main/backend/src/main/java/com/contractguard/ContractGuardApplication.java): `backend/src/main/java/com/contractguard/ContractGuardApplication.java`
- [Authentication](https://github.com/anuragbodkhe/contractguard-ai/blob/main/backend/src/main/java/com/contractguard/auth/AuthService.java): `backend/src/main/java/com/contractguard/auth/AuthService.java`
- [Contract intake](https://github.com/anuragbodkhe/contractguard-ai/blob/main/backend/src/main/java/com/contractguard/contract/ContractService.java): `backend/src/main/java/com/contractguard/contract/ContractService.java`
- [Document storage](https://github.com/anuragbodkhe/contractguard-ai/blob/main/backend/src/main/java/com/contractguard/document/StorageService.java): `backend/src/main/java/com/contractguard/document/StorageService.java`
- [Analysis orchestration](https://github.com/anuragbodkhe/contractguard-ai/blob/main/backend/src/main/java/com/contractguard/analysis/AnalysisPipeline.java): `backend/src/main/java/com/contractguard/analysis/AnalysisPipeline.java`
- [Clause segmentation](https://github.com/anuragbodkhe/contractguard-ai/blob/main/backend/src/main/java/com/contractguard/clause/ClauseSegmentationService.java): `backend/src/main/java/com/contractguard/clause/ClauseSegmentationService.java`
- [Rule findings](https://github.com/anuragbodkhe/contractguard-ai/blob/main/backend/src/main/java/com/contractguard/ruleengine/RuleEngine.java): `backend/src/main/java/com/contractguard/ruleengine/RuleEngine.java`
- [Risk aggregation](https://github.com/anuragbodkhe/contractguard-ai/blob/main/backend/src/main/java/com/contractguard/risk/RiskAggregationService.java): `backend/src/main/java/com/contractguard/risk/RiskAggregationService.java`
- [Analysis views](https://github.com/anuragbodkhe/contractguard-ai/blob/main/backend/src/main/java/com/contractguard/analysis/AnalysisViewService.java): `backend/src/main/java/com/contractguard/analysis/AnalysisViewService.java`
- [Report generation](https://github.com/anuragbodkhe/contractguard-ai/blob/main/backend/src/main/java/com/contractguard/report/ReportService.java): `backend/src/main/java/com/contractguard/report/ReportService.java`
- [Contract Q&A](https://github.com/anuragbodkhe/contractguard-ai/blob/main/backend/src/main/java/com/contractguard/retrieval/ContractQaService.java): `backend/src/main/java/com/contractguard/retrieval/ContractQaService.java`
- [Vector retrieval](https://github.com/anuragbodkhe/contractguard-ai/blob/main/backend/src/main/java/com/contractguard/retrieval/EmbeddingStore.java): `backend/src/main/java/com/contractguard/retrieval/EmbeddingStore.java`
- [ML service client](https://github.com/anuragbodkhe/contractguard-ai/blob/main/backend/src/main/java/com/contractguard/ml/client/MlServiceClient.java): `backend/src/main/java/com/contractguard/ml/client/MlServiceClient.java`
- [Model registry](https://github.com/anuragbodkhe/contractguard-ai/blob/main/backend/src/main/java/com/contractguard/admin/ModelRegistryService.java): `backend/src/main/java/com/contractguard/admin/ModelRegistryService.java`
- [Explanations](https://github.com/anuragbodkhe/contractguard-ai/blob/main/backend/src/main/java/com/contractguard/llm/ExplanationService.java): `backend/src/main/java/com/contractguard/llm/ExplanationService.java`
- **PostgreSQL**

### ML inference

- [ML inference API](https://github.com/anuragbodkhe/contractguard-ai/blob/main/ml-service/app/main.py): `ml-service/app/main.py`
- [Model manager](https://github.com/anuragbodkhe/contractguard-ai/blob/main/ml-service/app/inference/manager.py): `ml-service/app/inference/manager.py`
- [Five task models](https://github.com/anuragbodkhe/contractguard-ai/tree/main/ml-service/app/models): `ml-service/app/models`

### Legal knowledge

- [Legal sources](https://github.com/anuragbodkhe/contractguard-ai/blob/main/backend/src/main/java/com/contractguard/legalsource/LegalSourceService.java): `backend/src/main/java/com/contractguard/legalsource/LegalSourceService.java`

### Other components

- **Contract analyst**
- **Optional LLM provider**

## Connections

- Contract analyst → Web application: uses (evidence: `README.md`)
- Web application → Spring API: sends requests (evidence: `README.md`)
- Spring API → Authentication: authenticates
- Spring API → Contract intake: accepts uploads (evidence: `README.md`)
- Contract intake → Document storage: stores files (evidence: `backend/src/main/java/com/contractguard/contract/ContractService.java`)
- Spring API → Analysis orchestration: starts analysis (evidence: `README.md`)
- Analysis orchestration → Clause segmentation: segments clauses (evidence: `backend/src/main/java/com/contractguard/analysis/AnalysisPipeline.java`)
- Analysis orchestration → ML service client: requests predictions (evidence: `README.md`)
- ML service client → ML inference API: calls inference (evidence: `README.md`)
- ML inference API → Model manager: dispatches inference (evidence: `ml-service/app/main.py`)
- Model manager → Five task models: holds models (evidence: `ml-service/app/inference/manager.py`)
- Analysis orchestration → Rule findings: evaluates rules (evidence: `backend/src/main/java/com/contractguard/analysis/AnalysisPipeline.java`)
- Analysis orchestration → Risk aggregation: aggregates risk (evidence: `backend/src/main/java/com/contractguard/analysis/AnalysisPipeline.java`)
- Analysis orchestration → PostgreSQL: persists findings (evidence: `README.md`)
- Spring API → Analysis views: serves results
- Spring API → Report generation: provides reports (evidence: `README.md`)
- Report generation → Legal sources: includes sources (evidence: `backend/src/main/java/com/contractguard/report/ReportService.java`)
- Spring API → Contract Q&A: offers Q&A
- Contract Q&A → Vector retrieval: retrieves vectors (evidence: `backend/src/main/java/com/contractguard/retrieval/ContractQaService.java`)
- Contract Q&A → ML service client: requests embeddings (evidence: `backend/src/main/java/com/contractguard/retrieval/ContractQaService.java`)
- Spring API → Model registry: manages models
- Model registry → PostgreSQL: records versions (evidence: `backend/src/main/java/com/contractguard/admin/ModelRegistryService.java`)
- Analysis orchestration → Explanations: builds explanations (evidence: `backend/src/main/java/com/contractguard/analysis/AnalysisPipeline.java`)
- Explanations → Optional LLM provider: optionally generates (evidence: `backend/src/main/java/com/contractguard/llm/ExplanationService.java`)