# nanikandikonda/schemeconnectai architecture

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

- Interactive diagram: https://gitdiagram.com/nanikandikonda/schemeconnectai
- Repository: https://github.com/nanikandikonda/schemeconnectai

## Overview

SchemeConnect AI helps citizens discover Indian government schemes and assess eligibility through a conversational web app. The main workflow gathers profile details, requests clarification when important information is missing, narrows scheme candidates, retrieves relevant scheme content, evaluates eligibility, ranks results, and generates a grounded response. The frontend also provides home, scheme-browsing, and how-it-works pages. The conversation flow is documented in sampled source; route internals and several supporting modules were not sampled, so their wiring is shown only where the tree and sampled entry points support it.

Main entry points: [`backend/conversation/conversation_manager.py`](https://github.com/nanikandikonda/schemeconnectai/blob/main/backend/conversation/conversation_manager.py) (Conversation manager), [`backend/main.py`](https://github.com/nanikandikonda/schemeconnectai/blob/main/backend/main.py) (FastAPI app), [`frontend/src/services/api.js`](https://github.com/nanikandikonda/schemeconnectai/blob/main/frontend/src/services/api.js) (API client), [`backend/api/routes/schemes.py`](https://github.com/nanikandikonda/schemeconnectai/blob/main/backend/api/routes/schemes.py) (Scheme route)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web application"]
  node_webapp["React app<br/>[App.jsx]"]
  node_chatpage["Chat page<br/>[Chat.jsx]"]
  node_scheme_pages["Scheme pages<br/>[Schemes.jsx]"]
  node_api_client["API client<br/>[api.js]"]
end

subgraph group_api["API entry"]
  node_fastapi["FastAPI app<br/>[main.py]"]
  node_chat_route["Chat route<br/>[chat.py]"]
  node_scheme_route["Scheme route<br/>[schemes.py]"]
end

subgraph group_conversation["Conversation workflow"]
  node_conversation_manager["Conversation manager"]
  node_profile_extractor["Profile extraction"]
  node_missing_info["Missing-info check<br/>[missing_info.py]"]
  node_clarification["Clarification generation"]
  node_generation["Response generation"]
  node_citizen_model["Citizen profile<br/>[citizen.py]"]
end

subgraph group_schemes["Scheme matching"]
  node_scheme_filter["Candidate filtering<br/>[scheme_filter.py]"]
  node_eligibility["Eligibility engine"]
  node_ranking["Scheme ranking<br/>[ranking_service.py]"]
end

subgraph group_knowledge["Scheme knowledge"]
  node_scheme_loader["Scheme loader<br/>[scheme_loader.py]"]
  node_retriever["Semantic retrieval<br/>[retriever.py]"]
  node_vector_store[("Vector store<br/>[vector_store.py]")]
  node_rag_context["Context builder<br/>[context_builder.py]"]
  node_scheme_model["Scheme model<br/>[scheme.py]"]
end

node_citizen(("Citizen"))
node_gemini["Gemini service"]

node_citizen -->|"asks about schemes"| node_chatpage
node_webapp -->|"routes to"| node_chatpage
node_webapp -->|"routes to"| node_scheme_pages
node_chatpage -->|"submits messages"| node_api_client
node_scheme_pages -->|"requests schemes"| node_api_client
node_api_client -->|"sends requests"| node_chat_route
node_api_client -->|"sends requests"| node_scheme_route
node_fastapi -->|"registers route"| node_chat_route
node_fastapi -->|"registers route"| node_scheme_route
node_fastapi -->|"loads schemes"| node_scheme_loader
node_fastapi -->|"indexes schemes"| node_vector_store
node_chat_route -->|"processes messages"| node_conversation_manager
node_scheme_route -->|"loads scheme data"| node_scheme_loader
node_conversation_manager -->|"extracts profile"| node_profile_extractor
node_conversation_manager -->|"checks required fields"| node_missing_info
node_conversation_manager -->|"requests clarification"| node_clarification
node_conversation_manager -->|"builds profile"| node_citizen_model
node_conversation_manager -->|"filters schemes"| node_scheme_filter
node_conversation_manager -->|"retrieves candidates"| node_retriever
node_retriever -->|"queries chunks"| node_vector_store
node_conversation_manager -->|"builds context"| node_rag_context
node_conversation_manager -->|"evaluates schemes"| node_eligibility
node_conversation_manager -->|"ranks evaluations"| node_ranking
node_conversation_manager -->|"generates answer"| node_generation
node_generation -.->|"generates text"| node_gemini
node_scheme_loader -->|"loads scheme records"| node_scheme_model
node_conversation_manager -->|"uses scheme records"| node_scheme_model
node_scheme_route -->|"returns scheme data"| node_scheme_model

click node_webapp "https://github.com/nanikandikonda/schemeconnectai/blob/main/frontend/src/App.jsx"
click node_chatpage "https://github.com/nanikandikonda/schemeconnectai/blob/main/frontend/src/pages/Chat.jsx"
click node_scheme_pages "https://github.com/nanikandikonda/schemeconnectai/blob/main/frontend/src/pages/Schemes.jsx"
click node_api_client "https://github.com/nanikandikonda/schemeconnectai/blob/main/frontend/src/services/api.js"
click node_fastapi "https://github.com/nanikandikonda/schemeconnectai/blob/main/backend/main.py"
click node_chat_route "https://github.com/nanikandikonda/schemeconnectai/blob/main/backend/api/routes/chat.py"
click node_scheme_route "https://github.com/nanikandikonda/schemeconnectai/blob/main/backend/api/routes/schemes.py"
click node_scheme_loader "https://github.com/nanikandikonda/schemeconnectai/blob/main/backend/data/scheme_loader.py"
click node_conversation_manager "https://github.com/nanikandikonda/schemeconnectai/blob/main/backend/conversation/conversation_manager.py"
click node_profile_extractor "https://github.com/nanikandikonda/schemeconnectai/blob/main/backend/llm/profile_extractor.py"
click node_missing_info "https://github.com/nanikandikonda/schemeconnectai/blob/main/backend/conversation/missing_info.py"
click node_clarification "https://github.com/nanikandikonda/schemeconnectai/blob/main/backend/llm/response_generator.py"
click node_scheme_filter "https://github.com/nanikandikonda/schemeconnectai/blob/main/backend/services/scheme_filter.py"
click node_retriever "https://github.com/nanikandikonda/schemeconnectai/blob/main/backend/rag/retriever.py"
click node_vector_store "https://github.com/nanikandikonda/schemeconnectai/blob/main/backend/rag/vector_store.py"
click node_rag_context "https://github.com/nanikandikonda/schemeconnectai/blob/main/backend/rag/context_builder.py"
click node_eligibility "https://github.com/nanikandikonda/schemeconnectai/blob/main/backend/eligibility/eligibility_engine.py"
click node_ranking "https://github.com/nanikandikonda/schemeconnectai/blob/main/backend/services/ranking_service.py"
click node_generation "https://github.com/nanikandikonda/schemeconnectai/blob/main/backend/services/generation_service.py"
click node_scheme_model "https://github.com/nanikandikonda/schemeconnectai/blob/main/backend/models/scheme.py"
click node_citizen_model "https://github.com/nanikandikonda/schemeconnectai/blob/main/backend/models/citizen.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_webapp,node_chatpage,node_scheme_pages,node_api_client toneBlue
class node_fastapi,node_chat_route,node_scheme_route toneAmber
class node_conversation_manager,node_profile_extractor,node_missing_info,node_clarification,node_generation,node_citizen_model toneMint
class node_scheme_filter,node_eligibility,node_ranking toneRose
class node_scheme_loader,node_retriever,node_vector_store,node_rag_context,node_scheme_model,node_citizen,node_gemini toneIndigo
```

## Components

### Web application

- [React app](https://github.com/nanikandikonda/schemeconnectai/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Chat page](https://github.com/nanikandikonda/schemeconnectai/blob/main/frontend/src/pages/Chat.jsx): `frontend/src/pages/Chat.jsx`
- [Scheme pages](https://github.com/nanikandikonda/schemeconnectai/blob/main/frontend/src/pages/Schemes.jsx): `frontend/src/pages/Schemes.jsx`
- [API client](https://github.com/nanikandikonda/schemeconnectai/blob/main/frontend/src/services/api.js): `frontend/src/services/api.js`

### API entry

- [FastAPI app](https://github.com/nanikandikonda/schemeconnectai/blob/main/backend/main.py): `backend/main.py`
- [Chat route](https://github.com/nanikandikonda/schemeconnectai/blob/main/backend/api/routes/chat.py): `backend/api/routes/chat.py`
- [Scheme route](https://github.com/nanikandikonda/schemeconnectai/blob/main/backend/api/routes/schemes.py): `backend/api/routes/schemes.py`

### Conversation workflow

- [Conversation manager](https://github.com/nanikandikonda/schemeconnectai/blob/main/backend/conversation/conversation_manager.py): `backend/conversation/conversation_manager.py`
- [Profile extraction](https://github.com/nanikandikonda/schemeconnectai/blob/main/backend/llm/profile_extractor.py): `backend/llm/profile_extractor.py`
- [Missing-info check](https://github.com/nanikandikonda/schemeconnectai/blob/main/backend/conversation/missing_info.py): `backend/conversation/missing_info.py`
- [Clarification generation](https://github.com/nanikandikonda/schemeconnectai/blob/main/backend/llm/response_generator.py): `backend/llm/response_generator.py`
- [Response generation](https://github.com/nanikandikonda/schemeconnectai/blob/main/backend/services/generation_service.py): `backend/services/generation_service.py`
- [Citizen profile](https://github.com/nanikandikonda/schemeconnectai/blob/main/backend/models/citizen.py): `backend/models/citizen.py`

### Scheme matching

- [Candidate filtering](https://github.com/nanikandikonda/schemeconnectai/blob/main/backend/services/scheme_filter.py): `backend/services/scheme_filter.py`
- [Eligibility engine](https://github.com/nanikandikonda/schemeconnectai/blob/main/backend/eligibility/eligibility_engine.py): `backend/eligibility/eligibility_engine.py`
- [Scheme ranking](https://github.com/nanikandikonda/schemeconnectai/blob/main/backend/services/ranking_service.py): `backend/services/ranking_service.py`

### Scheme knowledge

- [Scheme loader](https://github.com/nanikandikonda/schemeconnectai/blob/main/backend/data/scheme_loader.py): `backend/data/scheme_loader.py`
- [Semantic retrieval](https://github.com/nanikandikonda/schemeconnectai/blob/main/backend/rag/retriever.py): `backend/rag/retriever.py`
- [Vector store](https://github.com/nanikandikonda/schemeconnectai/blob/main/backend/rag/vector_store.py): `backend/rag/vector_store.py`
- [Context builder](https://github.com/nanikandikonda/schemeconnectai/blob/main/backend/rag/context_builder.py): `backend/rag/context_builder.py`
- [Scheme model](https://github.com/nanikandikonda/schemeconnectai/blob/main/backend/models/scheme.py): `backend/models/scheme.py`

### Other components

- **Citizen**
- **Gemini service**

## Connections

- Citizen → Chat page: asks about schemes
- React app → Chat page: routes to
- React app → Scheme pages: routes to
- Chat page → API client: submits messages
- Scheme pages → API client: requests schemes
- API client → Chat route: sends requests
- API client → Scheme route: sends requests
- FastAPI app → Chat route: registers route
- FastAPI app → Scheme route: registers route
- FastAPI app → Scheme loader: loads schemes
- FastAPI app → Vector store: indexes schemes
- Chat route → Conversation manager: processes messages
- Scheme route → Scheme loader: loads scheme data
- Conversation manager → Profile extraction: extracts profile
- Conversation manager → Missing-info check: checks required fields
- Conversation manager → Clarification generation: requests clarification
- Conversation manager → Citizen profile: builds profile
- Conversation manager → Candidate filtering: filters schemes
- Conversation manager → Semantic retrieval: retrieves candidates
- Semantic retrieval → Vector store: queries chunks
- Conversation manager → Context builder: builds context
- Conversation manager → Eligibility engine: evaluates schemes
- Conversation manager → Scheme ranking: ranks evaluations
- Conversation manager → Response generation: generates answer
- Response generation → Gemini service: generates text
- Scheme loader → Scheme model: loads scheme records
- Conversation manager → Scheme model: uses scheme records
- Scheme route → Scheme model: returns scheme data