# mohamedshafars19/bharatspec-ai architecture

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

- Interactive diagram: https://gitdiagram.com/mohamedshafars19/bharatspec-ai
- Repository: https://github.com/mohamedshafars19/bharatspec-ai

## Overview

BharatSpec AI is a procurement-specification assistant. Procurement staff submit a requirement or tender document; the application parses it, asks for clarifications, audits readiness, finds relevant Indian Standards, reviews relationships and versions, and can produce an improved specification and report. The graph preserves project workspaces, standards exploration, and authentication as supporting capabilities. Backend service-call details are based on indexed imports and excerpts; unsampled route behavior is represented only where the README documents it.

Main entry points: [`backend/app/main.py`](https://github.com/mohamedshafars19/bharatspec-ai/blob/main/backend/app/main.py) (FastAPI application), [`backend/app/services/recommendation_service.py`](https://github.com/mohamedshafars19/bharatspec-ai/blob/main/backend/app/services/recommendation_service.py) (Standards recommendation), [`frontend/src/services/api.ts`](https://github.com/mohamedshafars19/bharatspec-ai/blob/main/frontend/src/services/api.ts) (API client), [`backend/app/api/routes/analyze.py`](https://github.com/mohamedshafars19/bharatspec-ai/blob/main/backend/app/api/routes/analyze.py) (Analysis endpoint)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workspace["User Workspace"]
  node_web["Web application<br/>[App.tsx]"]
  node_auth["Authentication<br/>[AuthContext.tsx]"]
  node_analyze_ui["Analysis workspace<br/>[Analyze.tsx]"]
  node_project_ui["Project workspace<br/>[ProjectDetail.tsx]"]
  node_standards_ui["Standards browser<br/>[Standards.tsx]"]
  node_report_ui["Report export"]
  node_relationship_ui["Relationship visualization"]
end

subgraph group_analysis["Requirement Analysis"]
  node_document_route["Document intake<br/>[documents.py]"]
  node_analyze_route["Analysis endpoint<br/>[analyze.py]"]
  node_requirement_parse["Requirement parsing"]
  node_clarification["Clarifying questions"]
  node_gap_audit["Specification audit"]
  node_spec_route["Specification endpoints<br/>[specification.py]"]
  node_improvement["Specification drafting"]
end

subgraph group_standards["Standards Intelligence"]
  node_recommendation["Standards recommendation"]
  node_vector_search["Vector retrieval"]
  node_embedding["Text embeddings"]
  node_standards_catalog["Standards catalog"]
  node_relationship_graph["Relationship graph"]
  node_standards_route["Standards endpoints<br/>[standards.py]"]
end

subgraph group_persistence["Workspace Data"]
  node_database[("SQLite workspace store<br/>[db.py]")]
end

subgraph group_platform["Application Platform"]
  node_api_client["API client<br/>[api.ts]"]
  node_gemini["Gemini service<br/>[gemini_service.py]"]
  node_schemas["API domain schemas<br/>[schemas.py]"]
  node_config["Runtime configuration<br/>[config.py]"]
  node_server["FastAPI application<br/>[main.py]"]
end

node_staff(("Procurement staff"))

node_staff -->|"uses"| node_web
node_web -->|"routes to"| node_analyze_ui
node_web -->|"provides context"| node_auth
node_staff -->|"submits requirement"| node_analyze_ui
node_analyze_ui -->|"requests analysis"| node_api_client
node_api_client -->|"calls endpoint"| node_analyze_route
node_server -->|"mounts"| node_analyze_route
node_analyze_ui -.->|"uploads tender"| node_document_route
node_server -->|"mounts"| node_document_route
node_analyze_route -->|"parses requirement"| node_requirement_parse
node_analyze_route -->|"gets questions"| node_clarification
node_analyze_route -->|"reads and saves"| node_database
node_requirement_parse -->|"uses when configured"| node_gemini
node_analyze_route -->|"gets standards"| node_recommendation
node_recommendation -->|"retrieves matches"| node_vector_search
node_recommendation -->|"enriches results"| node_standards_catalog
node_recommendation -->|"audits requirement"| node_gap_audit
node_recommendation -->|"checks ambiguity"| node_clarification
node_recommendation -->|"adds relationships"| node_relationship_graph
node_recommendation -->|"drafts specification"| node_improvement
node_vector_search -->|"encodes text"| node_embedding
node_vector_search -->|"indexes catalog"| node_standards_catalog
node_staff -->|"explores standards"| node_standards_ui
node_standards_ui -->|"requests standards"| node_api_client
node_api_client -->|"calls endpoint"| node_standards_route
node_server -->|"mounts"| node_standards_route
node_standards_route -->|"searches catalog"| node_standards_catalog
node_standards_route -->|"gets graph"| node_relationship_graph
node_relationship_ui -.->|"loads graph"| node_api_client
node_staff -->|"requests audit or draft"| node_spec_route
node_server -->|"mounts"| node_spec_route
node_spec_route -->|"audits specification"| node_gap_audit
node_spec_route -->|"improves specification"| node_improvement
node_staff -->|"exports report"| node_report_ui
node_project_ui -->|"loads project"| node_api_client
node_staff -->|"organizes work"| node_project_ui
node_auth -->|"authenticates"| node_api_client
node_database -->|"gets database setting"| node_config
node_server -->|"initializes"| node_database
node_server -->|"loads catalog"| node_standards_catalog
node_server -->|"loads index"| node_vector_search
node_gemini -->|"reads model settings"| node_config

click node_web "https://github.com/mohamedshafars19/bharatspec-ai/blob/main/frontend/src/App.tsx"
click node_auth "https://github.com/mohamedshafars19/bharatspec-ai/blob/main/frontend/src/context/AuthContext.tsx"
click node_analyze_ui "https://github.com/mohamedshafars19/bharatspec-ai/blob/main/frontend/src/pages/Analyze.tsx"
click node_project_ui "https://github.com/mohamedshafars19/bharatspec-ai/blob/main/frontend/src/pages/ProjectDetail.tsx"
click node_standards_ui "https://github.com/mohamedshafars19/bharatspec-ai/blob/main/frontend/src/pages/Standards.tsx"
click node_api_client "https://github.com/mohamedshafars19/bharatspec-ai/blob/main/frontend/src/services/api.ts"
click node_document_route "https://github.com/mohamedshafars19/bharatspec-ai/blob/main/backend/app/api/routes/documents.py"
click node_analyze_route "https://github.com/mohamedshafars19/bharatspec-ai/blob/main/backend/app/api/routes/analyze.py"
click node_requirement_parse "https://github.com/mohamedshafars19/bharatspec-ai/blob/main/backend/app/services/requirement_service.py"
click node_clarification "https://github.com/mohamedshafars19/bharatspec-ai/blob/main/backend/app/services/clarification_service.py"
click node_gap_audit "https://github.com/mohamedshafars19/bharatspec-ai/blob/main/backend/app/services/gap_detection_service.py"
click node_recommendation "https://github.com/mohamedshafars19/bharatspec-ai/blob/main/backend/app/services/recommendation_service.py"
click node_vector_search "https://github.com/mohamedshafars19/bharatspec-ai/blob/main/backend/app/services/vector_search_service.py"
click node_embedding "https://github.com/mohamedshafars19/bharatspec-ai/blob/main/backend/app/services/embedding_service.py"
click node_standards_catalog "https://github.com/mohamedshafars19/bharatspec-ai/blob/main/backend/app/services/standards_service.py"
click node_relationship_graph "https://github.com/mohamedshafars19/bharatspec-ai/blob/main/backend/app/services/relationship_graph_service.py"
click node_standards_route "https://github.com/mohamedshafars19/bharatspec-ai/blob/main/backend/app/api/routes/standards.py"
click node_spec_route "https://github.com/mohamedshafars19/bharatspec-ai/blob/main/backend/app/api/routes/specification.py"
click node_improvement "https://github.com/mohamedshafars19/bharatspec-ai/blob/main/backend/app/services/spec_improvement_service.py"
click node_gemini "https://github.com/mohamedshafars19/bharatspec-ai/blob/main/backend/app/services/gemini_service.py"
click node_database "https://github.com/mohamedshafars19/bharatspec-ai/blob/main/backend/app/database/db.py"
click node_schemas "https://github.com/mohamedshafars19/bharatspec-ai/blob/main/backend/app/models/schemas.py"
click node_config "https://github.com/mohamedshafars19/bharatspec-ai/blob/main/backend/app/core/config.py"
click node_server "https://github.com/mohamedshafars19/bharatspec-ai/blob/main/backend/app/main.py"
click node_report_ui "https://github.com/mohamedshafars19/bharatspec-ai/blob/main/frontend/src/components/ExportReportModal.tsx"
click node_relationship_ui "https://github.com/mohamedshafars19/bharatspec-ai/blob/main/frontend/src/components/StandardRelationshipGraph.tsx"

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,node_auth,node_analyze_ui,node_project_ui,node_standards_ui,node_report_ui,node_relationship_ui toneBlue
class node_document_route,node_analyze_route,node_requirement_parse,node_clarification,node_gap_audit,node_spec_route,node_improvement toneAmber
class node_recommendation,node_vector_search,node_embedding,node_standards_catalog,node_relationship_graph,node_standards_route toneMint
class node_database toneRose
class node_api_client,node_gemini,node_schemas,node_config,node_server,node_staff toneIndigo
```

## Components

### User Workspace

- [Web application](https://github.com/mohamedshafars19/bharatspec-ai/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Authentication](https://github.com/mohamedshafars19/bharatspec-ai/blob/main/frontend/src/context/AuthContext.tsx): `frontend/src/context/AuthContext.tsx`
- [Analysis workspace](https://github.com/mohamedshafars19/bharatspec-ai/blob/main/frontend/src/pages/Analyze.tsx): `frontend/src/pages/Analyze.tsx`
- [Project workspace](https://github.com/mohamedshafars19/bharatspec-ai/blob/main/frontend/src/pages/ProjectDetail.tsx): `frontend/src/pages/ProjectDetail.tsx`
- [Standards browser](https://github.com/mohamedshafars19/bharatspec-ai/blob/main/frontend/src/pages/Standards.tsx): `frontend/src/pages/Standards.tsx`
- [Report export](https://github.com/mohamedshafars19/bharatspec-ai/blob/main/frontend/src/components/ExportReportModal.tsx): `frontend/src/components/ExportReportModal.tsx`
- [Relationship visualization](https://github.com/mohamedshafars19/bharatspec-ai/blob/main/frontend/src/components/StandardRelationshipGraph.tsx): `frontend/src/components/StandardRelationshipGraph.tsx`

### Requirement Analysis

- [Document intake](https://github.com/mohamedshafars19/bharatspec-ai/blob/main/backend/app/api/routes/documents.py): `backend/app/api/routes/documents.py`
- [Analysis endpoint](https://github.com/mohamedshafars19/bharatspec-ai/blob/main/backend/app/api/routes/analyze.py): `backend/app/api/routes/analyze.py`
- [Requirement parsing](https://github.com/mohamedshafars19/bharatspec-ai/blob/main/backend/app/services/requirement_service.py): `backend/app/services/requirement_service.py`
- [Clarifying questions](https://github.com/mohamedshafars19/bharatspec-ai/blob/main/backend/app/services/clarification_service.py): `backend/app/services/clarification_service.py`
- [Specification audit](https://github.com/mohamedshafars19/bharatspec-ai/blob/main/backend/app/services/gap_detection_service.py): `backend/app/services/gap_detection_service.py`
- [Specification endpoints](https://github.com/mohamedshafars19/bharatspec-ai/blob/main/backend/app/api/routes/specification.py): `backend/app/api/routes/specification.py`
- [Specification drafting](https://github.com/mohamedshafars19/bharatspec-ai/blob/main/backend/app/services/spec_improvement_service.py): `backend/app/services/spec_improvement_service.py`

### Standards Intelligence

- [Standards recommendation](https://github.com/mohamedshafars19/bharatspec-ai/blob/main/backend/app/services/recommendation_service.py): `backend/app/services/recommendation_service.py`
- [Vector retrieval](https://github.com/mohamedshafars19/bharatspec-ai/blob/main/backend/app/services/vector_search_service.py): `backend/app/services/vector_search_service.py`
- [Text embeddings](https://github.com/mohamedshafars19/bharatspec-ai/blob/main/backend/app/services/embedding_service.py): `backend/app/services/embedding_service.py`
- [Standards catalog](https://github.com/mohamedshafars19/bharatspec-ai/blob/main/backend/app/services/standards_service.py): `backend/app/services/standards_service.py`
- [Relationship graph](https://github.com/mohamedshafars19/bharatspec-ai/blob/main/backend/app/services/relationship_graph_service.py): `backend/app/services/relationship_graph_service.py`
- [Standards endpoints](https://github.com/mohamedshafars19/bharatspec-ai/blob/main/backend/app/api/routes/standards.py): `backend/app/api/routes/standards.py`

### Workspace Data

- [SQLite workspace store](https://github.com/mohamedshafars19/bharatspec-ai/blob/main/backend/app/database/db.py): `backend/app/database/db.py`

### Application Platform

- [API client](https://github.com/mohamedshafars19/bharatspec-ai/blob/main/frontend/src/services/api.ts): `frontend/src/services/api.ts`
- [Gemini service](https://github.com/mohamedshafars19/bharatspec-ai/blob/main/backend/app/services/gemini_service.py): `backend/app/services/gemini_service.py`
- [API domain schemas](https://github.com/mohamedshafars19/bharatspec-ai/blob/main/backend/app/models/schemas.py): `backend/app/models/schemas.py`
- [Runtime configuration](https://github.com/mohamedshafars19/bharatspec-ai/blob/main/backend/app/core/config.py): `backend/app/core/config.py`
- [FastAPI application](https://github.com/mohamedshafars19/bharatspec-ai/blob/main/backend/app/main.py): `backend/app/main.py`

### Other components

- **Procurement staff**

## Connections

- Procurement staff → Web application: uses (evidence: `README.md`)
- Web application → Analysis workspace: routes to (evidence: `frontend/src/App.tsx`)
- Web application → Authentication: provides context (evidence: `frontend/src/App.tsx`)
- Procurement staff → Analysis workspace: submits requirement (evidence: `README.md`)
- Analysis workspace → API client: requests analysis (evidence: `frontend/src/pages/Analyze.tsx`)
- API client → Analysis endpoint: calls endpoint (evidence: `frontend/src/services/api.ts`)
- FastAPI application → Analysis endpoint: mounts (evidence: `backend/app/main.py`)
- Analysis workspace → Document intake: uploads tender (evidence: `README.md`)
- FastAPI application → Document intake: mounts (evidence: `backend/app/main.py`)
- Analysis endpoint → Requirement parsing: parses requirement (evidence: `backend/app/api/routes/analyze.py`)
- Analysis endpoint → Clarifying questions: gets questions (evidence: `backend/app/api/routes/analyze.py`)
- Analysis endpoint → SQLite workspace store: reads and saves (evidence: `backend/app/api/routes/analyze.py`)
- Requirement parsing → Gemini service: uses when configured (evidence: `backend/app/services/requirement_service.py`)
- Analysis endpoint → Standards recommendation: gets standards (evidence: `backend/app/api/routes/analyze.py`)
- Standards recommendation → Vector retrieval: retrieves matches (evidence: `backend/app/services/recommendation_service.py`)
- Standards recommendation → Standards catalog: enriches results (evidence: `backend/app/services/recommendation_service.py`)
- Standards recommendation → Specification audit: audits requirement (evidence: `backend/app/services/recommendation_service.py`)
- Standards recommendation → Clarifying questions: checks ambiguity (evidence: `backend/app/services/recommendation_service.py`)
- Standards recommendation → Relationship graph: adds relationships (evidence: `backend/app/services/recommendation_service.py`)
- Standards recommendation → Specification drafting: drafts specification (evidence: `backend/app/services/recommendation_service.py`)
- Vector retrieval → Text embeddings: encodes text (evidence: `backend/app/services/vector_search_service.py`)
- Vector retrieval → Standards catalog: indexes catalog (evidence: `backend/app/services/vector_search_service.py`)
- Procurement staff → Standards browser: explores standards (evidence: `README.md`)
- Standards browser → API client: requests standards (evidence: `frontend/src/pages/Standards.tsx`)
- API client → Standards endpoints: calls endpoint (evidence: `frontend/src/services/api.ts`)
- FastAPI application → Standards endpoints: mounts (evidence: `backend/app/main.py`)
- Standards endpoints → Standards catalog: searches catalog (evidence: `backend/app/api/routes/standards.py`)
- Standards endpoints → Relationship graph: gets graph (evidence: `backend/app/api/routes/standards.py`)
- Relationship visualization → API client: loads graph (evidence: `frontend/src/pages/StandardDetail.tsx`)
- Procurement staff → Specification endpoints: requests audit or draft (evidence: `README.md`)
- FastAPI application → Specification endpoints: mounts (evidence: `backend/app/main.py`)
- Specification endpoints → Specification audit: audits specification (evidence: `backend/app/api/routes/specification.py`)
- Specification endpoints → Specification drafting: improves specification (evidence: `backend/app/api/routes/specification.py`)
- Procurement staff → Report export: exports report (evidence: `README.md`)
- Project workspace → API client: loads project (evidence: `frontend/src/pages/ProjectDetail.tsx`)
- Procurement staff → Project workspace: organizes work (evidence: `README.md`)
- Authentication → API client: authenticates (evidence: `frontend/src/context/AuthContext.tsx`)
- SQLite workspace store → Runtime configuration: gets database setting (evidence: `backend/app/database/db.py`)
- FastAPI application → SQLite workspace store: initializes (evidence: `backend/app/main.py`)
- FastAPI application → Standards catalog: loads catalog (evidence: `backend/app/main.py`)
- FastAPI application → Vector retrieval: loads index (evidence: `backend/app/main.py`)
- Gemini service → Runtime configuration: reads model settings (evidence: `backend/app/services/gemini_service.py`)
