# aspathak2705/rupeetrace architecture

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

- Interactive diagram: https://gitdiagram.com/aspathak2705/rupeetrace
- Repository: https://github.com/aspathak2705/rupeetrace

## Overview

RupeeTrace is a civic road-repair accountability platform. Citizens and municipal officers use the web app to inspect roads, complaints, repairs and evidence, or submit observations and clarifications; municipal users can also review audits and contractor performance and prioritize repair funding. The backend loads provenance-bearing civic records, links them into relationships, computes financial and accountability insights, and persists shared civic workflows in SQLite. The graph keeps major documented capabilities even where their implementation was not sampled; dashed, uncited links mark wiring that the excerpts do not establish.

Main entry points: [`rupeetrace/api/routes`](https://github.com/aspathak2705/rupeetrace/tree/main/rupeetrace/api/routes) (REST route handlers), [`frontend/src/App.tsx`](https://github.com/aspathak2705/rupeetrace/blob/main/frontend/src/App.tsx) (App navigation), [`frontend/src/api/client.ts`](https://github.com/aspathak2705/rupeetrace/blob/main/frontend/src/api/client.ts) (API client), [`rupeetrace/services/relationship_service.py`](https://github.com/aspathak2705/rupeetrace/blob/main/rupeetrace/services/relationship_service.py) (Relationship index)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web application"]
  node_app["App navigation<br/>[App.tsx]"]
  node_authui["Session context<br/>[AuthContext.tsx]"]
  node_client["API client<br/>[client.ts]"]
  node_roadviews["Road passport"]
  node_graphview["Money trace graph"]
  node_auditviews["Audit investigation"]
  node_accountviews["Accountability views"]
  node_planner["Next Rupee planner"]
  node_assistantui["AI assistant drawer"]
  node_caseview["Citizen-officer cases"]
end

subgraph group_api["API and access"]
  node_routes["REST route handlers"]
  node_auth["Role authorization<br/>[auth.py]"]
end

subgraph group_data["Civic data"]
  node_loader["Dataset ingestion<br/>[data_loader.py]"]
  node_entities["Domain entities<br/>[entities.py]"]
  node_relationships["Relationship index"]
  node_civicdb[("Civic SQLite store<br/>[civic_db.py]")]
end

subgraph group_insight["Financial intelligence"]
  node_money["Money trail analysis"]
  node_audit["Repair auditor<br/>[audit_service.py]"]
  node_fair["Contractor accountability"]
  node_allocation["Budget allocation"]
  node_graphsvc["Graph construction<br/>[graph_service.py]"]
  node_assistant["Evidence-grounded assistant"]
end

subgraph group_civic["Citizen workflows"]
  node_janmat["Citizen proposals<br/>[janmat_service.py]"]
  node_cases["Case workflow<br/>[case_service.py]"]
end

node_citizen(("Citizen or officer"))

node_citizen -->|"uses"| node_app
node_app -->|"provides session"| node_authui
node_authui -->|"logs in"| node_client
node_app -.->|"routes to"| node_roadviews
node_app -.->|"routes to"| node_graphview
node_app -.->|"routes to"| node_auditviews
node_app -.->|"routes to"| node_accountviews
node_app -->|"routes to"| node_planner
node_app -->|"renders"| node_assistantui
node_app -.->|"routes to"| node_caseview
node_roadviews -.->|"requests data"| node_client
node_graphview -.->|"requests graph"| node_client
node_auditviews -.->|"requests findings"| node_client
node_planner -->|"requests plans"| node_client
node_assistantui -->|"asks questions"| node_client
node_caseview -.->|"submits cases"| node_client
node_client -->|"HTTP requests"| node_routes
node_routes -.->|"checks roles"| node_auth
node_routes -.->|"dispatches"| node_money
node_routes -.->|"dispatches"| node_audit
node_routes -.->|"dispatches"| node_fair
node_routes -.->|"dispatches"| node_allocation
node_routes -.->|"dispatches"| node_graphsvc
node_routes -.->|"dispatches"| node_assistant
node_routes -.->|"dispatches"| node_janmat
node_routes -.->|"dispatches"| node_cases
node_loader -->|"constructs"| node_entities
node_relationships -->|"indexes records"| node_loader
node_money -.->|"reads relationships"| node_relationships
node_audit -->|"reads relationships"| node_relationships
node_graphsvc -->|"builds graph from"| node_relationships
node_assistant -->|"retrieves evidence"| node_relationships
node_janmat -->|"uses road context"| node_relationships
node_janmat -->|"persists proposals"| node_civicdb
node_cases -.->|"persists cases"| node_civicdb
node_assistant -.->|"optional AI service"| node_citizen

click node_app "https://github.com/aspathak2705/rupeetrace/blob/main/frontend/src/App.tsx"
click node_authui "https://github.com/aspathak2705/rupeetrace/blob/main/frontend/src/context/AuthContext.tsx"
click node_client "https://github.com/aspathak2705/rupeetrace/blob/main/frontend/src/api/client.ts"
click node_roadviews "https://github.com/aspathak2705/rupeetrace/blob/main/frontend/src/views/RoadPassportView.tsx"
click node_graphview "https://github.com/aspathak2705/rupeetrace/blob/main/frontend/src/views/VisualMoneyTraceGraphView.tsx"
click node_auditviews "https://github.com/aspathak2705/rupeetrace/blob/main/frontend/src/views/AuditsInvestigationView.tsx"
click node_accountviews "https://github.com/aspathak2705/rupeetrace/blob/main/frontend/src/views/FairAccountabilityView.tsx"
click node_planner "https://github.com/aspathak2705/rupeetrace/blob/main/frontend/src/views/NextRupeePlannerView.tsx"
click node_assistantui "https://github.com/aspathak2705/rupeetrace/blob/main/frontend/src/components/AIAssistantDrawer.tsx"
click node_caseview "https://github.com/aspathak2705/rupeetrace/blob/main/frontend/src/views/CitizenOfficerCasesView.tsx"
click node_routes "https://github.com/aspathak2705/rupeetrace/tree/main/rupeetrace/api/routes"
click node_auth "https://github.com/aspathak2705/rupeetrace/blob/main/rupeetrace/core/auth.py"
click node_loader "https://github.com/aspathak2705/rupeetrace/blob/main/rupeetrace/data/data_loader.py"
click node_entities "https://github.com/aspathak2705/rupeetrace/blob/main/rupeetrace/models/entities.py"
click node_relationships "https://github.com/aspathak2705/rupeetrace/blob/main/rupeetrace/services/relationship_service.py"
click node_civicdb "https://github.com/aspathak2705/rupeetrace/blob/main/rupeetrace/data/civic_db.py"
click node_money "https://github.com/aspathak2705/rupeetrace/blob/main/rupeetrace/services/money_trail_service.py"
click node_audit "https://github.com/aspathak2705/rupeetrace/blob/main/rupeetrace/services/audit_service.py"
click node_fair "https://github.com/aspathak2705/rupeetrace/blob/main/rupeetrace/services/accountability_service.py"
click node_allocation "https://github.com/aspathak2705/rupeetrace/blob/main/rupeetrace/services/next_rupee_service.py"
click node_graphsvc "https://github.com/aspathak2705/rupeetrace/blob/main/rupeetrace/services/graph_service.py"
click node_assistant "https://github.com/aspathak2705/rupeetrace/blob/main/rupeetrace/services/assistant_service.py"
click node_janmat "https://github.com/aspathak2705/rupeetrace/blob/main/rupeetrace/services/janmat_service.py"
click node_cases "https://github.com/aspathak2705/rupeetrace/blob/main/rupeetrace/services/case_service.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_app,node_authui,node_client,node_roadviews,node_graphview,node_auditviews,node_accountviews,node_planner,node_assistantui,node_caseview toneBlue
class node_routes,node_auth toneAmber
class node_loader,node_entities,node_relationships,node_civicdb toneMint
class node_money,node_audit,node_fair,node_allocation,node_graphsvc,node_assistant toneRose
class node_janmat,node_cases,node_citizen toneIndigo
```

## Components

### Web application

- [App navigation](https://github.com/aspathak2705/rupeetrace/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Session context](https://github.com/aspathak2705/rupeetrace/blob/main/frontend/src/context/AuthContext.tsx): `frontend/src/context/AuthContext.tsx`
- [API client](https://github.com/aspathak2705/rupeetrace/blob/main/frontend/src/api/client.ts): `frontend/src/api/client.ts`
- [Road passport](https://github.com/aspathak2705/rupeetrace/blob/main/frontend/src/views/RoadPassportView.tsx): `frontend/src/views/RoadPassportView.tsx`
- [Money trace graph](https://github.com/aspathak2705/rupeetrace/blob/main/frontend/src/views/VisualMoneyTraceGraphView.tsx): `frontend/src/views/VisualMoneyTraceGraphView.tsx`
- [Audit investigation](https://github.com/aspathak2705/rupeetrace/blob/main/frontend/src/views/AuditsInvestigationView.tsx): `frontend/src/views/AuditsInvestigationView.tsx`
- [Accountability views](https://github.com/aspathak2705/rupeetrace/blob/main/frontend/src/views/FairAccountabilityView.tsx): `frontend/src/views/FairAccountabilityView.tsx`
- [Next Rupee planner](https://github.com/aspathak2705/rupeetrace/blob/main/frontend/src/views/NextRupeePlannerView.tsx): `frontend/src/views/NextRupeePlannerView.tsx`
- [AI assistant drawer](https://github.com/aspathak2705/rupeetrace/blob/main/frontend/src/components/AIAssistantDrawer.tsx): `frontend/src/components/AIAssistantDrawer.tsx`
- [Citizen-officer cases](https://github.com/aspathak2705/rupeetrace/blob/main/frontend/src/views/CitizenOfficerCasesView.tsx): `frontend/src/views/CitizenOfficerCasesView.tsx`

### API and access

- [REST route handlers](https://github.com/aspathak2705/rupeetrace/tree/main/rupeetrace/api/routes): `rupeetrace/api/routes`
- [Role authorization](https://github.com/aspathak2705/rupeetrace/blob/main/rupeetrace/core/auth.py): `rupeetrace/core/auth.py`

### Civic data

- [Dataset ingestion](https://github.com/aspathak2705/rupeetrace/blob/main/rupeetrace/data/data_loader.py): `rupeetrace/data/data_loader.py`
- [Domain entities](https://github.com/aspathak2705/rupeetrace/blob/main/rupeetrace/models/entities.py): `rupeetrace/models/entities.py`
- [Relationship index](https://github.com/aspathak2705/rupeetrace/blob/main/rupeetrace/services/relationship_service.py): `rupeetrace/services/relationship_service.py`
- [Civic SQLite store](https://github.com/aspathak2705/rupeetrace/blob/main/rupeetrace/data/civic_db.py): `rupeetrace/data/civic_db.py`

### Financial intelligence

- [Money trail analysis](https://github.com/aspathak2705/rupeetrace/blob/main/rupeetrace/services/money_trail_service.py): `rupeetrace/services/money_trail_service.py`
- [Repair auditor](https://github.com/aspathak2705/rupeetrace/blob/main/rupeetrace/services/audit_service.py): `rupeetrace/services/audit_service.py`
- [Contractor accountability](https://github.com/aspathak2705/rupeetrace/blob/main/rupeetrace/services/accountability_service.py): `rupeetrace/services/accountability_service.py`
- [Budget allocation](https://github.com/aspathak2705/rupeetrace/blob/main/rupeetrace/services/next_rupee_service.py): `rupeetrace/services/next_rupee_service.py`
- [Graph construction](https://github.com/aspathak2705/rupeetrace/blob/main/rupeetrace/services/graph_service.py): `rupeetrace/services/graph_service.py`
- [Evidence-grounded assistant](https://github.com/aspathak2705/rupeetrace/blob/main/rupeetrace/services/assistant_service.py): `rupeetrace/services/assistant_service.py`

### Citizen workflows

- [Citizen proposals](https://github.com/aspathak2705/rupeetrace/blob/main/rupeetrace/services/janmat_service.py): `rupeetrace/services/janmat_service.py`
- [Case workflow](https://github.com/aspathak2705/rupeetrace/blob/main/rupeetrace/services/case_service.py): `rupeetrace/services/case_service.py`

### Other components

- **Citizen or officer**

## Connections

- Citizen or officer → App navigation: uses (evidence: `README.md`)
- App navigation → Session context: provides session (evidence: `frontend/src/App.tsx`)
- Session context → API client: logs in (evidence: `frontend/src/context/AuthContext.tsx`)
- App navigation → Road passport: routes to
- App navigation → Money trace graph: routes to
- App navigation → Audit investigation: routes to
- App navigation → Accountability views: routes to
- App navigation → Next Rupee planner: routes to (evidence: `frontend/src/App.tsx`)
- App navigation → AI assistant drawer: renders (evidence: `frontend/src/App.tsx`)
- App navigation → Citizen-officer cases: routes to
- Road passport → API client: requests data
- Money trace graph → API client: requests graph
- Audit investigation → API client: requests findings
- Next Rupee planner → API client: requests plans (evidence: `frontend/src/views/NextRupeePlannerView.tsx`)
- AI assistant drawer → API client: asks questions (evidence: `frontend/src/components/AIAssistantDrawer.tsx`)
- Citizen-officer cases → API client: submits cases
- API client → REST route handlers: HTTP requests (evidence: `frontend/src/api/client.ts`)
- REST route handlers → Role authorization: checks roles (evidence: `rupeetrace/api/routes/auth.py`)
- REST route handlers → Money trail analysis: dispatches
- REST route handlers → Repair auditor: dispatches
- REST route handlers → Contractor accountability: dispatches
- REST route handlers → Budget allocation: dispatches
- REST route handlers → Graph construction: dispatches
- REST route handlers → Evidence-grounded assistant: dispatches
- REST route handlers → Citizen proposals: dispatches
- REST route handlers → Case workflow: dispatches
- Dataset ingestion → Domain entities: constructs (evidence: `rupeetrace/data/data_loader.py`)
- Relationship index → Dataset ingestion: indexes records (evidence: `rupeetrace/services/relationship_service.py`)
- Money trail analysis → Relationship index: reads relationships
- Repair auditor → Relationship index: reads relationships (evidence: `rupeetrace/services/audit_service.py`)
- Graph construction → Relationship index: builds graph from (evidence: `rupeetrace/services/graph_service.py`)
- Evidence-grounded assistant → Relationship index: retrieves evidence (evidence: `rupeetrace/services/assistant_service.py`)
- Citizen proposals → Relationship index: uses road context (evidence: `rupeetrace/services/janmat_service.py`)
- Citizen proposals → Civic SQLite store: persists proposals (evidence: `rupeetrace/services/janmat_service.py`)
- Case workflow → Civic SQLite store: persists cases
- Evidence-grounded assistant → Citizen or officer: optional AI service
