# harshcodezzz/build-with-ai-hackathon architecture

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

- Interactive diagram: https://gitdiagram.com/harshcodezzz/build-with-ai-hackathon
- Repository: https://github.com/harshcodezzz/build-with-ai-hackathon

## Overview

JanSeva is a multilingual citizen-feedback platform that turns text or recorded complaints into tracked, analyzed infrastructure issues and policymaker priorities. The main path runs from the citizen portal through the backend and, for voice, transcription; complaints then enter the risk analyzer’s queued analysis, spatial clustering, and risk scoring, with results surfaced in citizen tracking and admin views. README-described integrations are included where source excerpts do not show their wiring; uncertain internal links are omitted.

Main entry points: [`risk-analyser/src/index.ts`](https://github.com/harshcodezzz/build-with-ai-hackathon/blob/main/risk-analyser/src/index.ts) (Risk service entry), [`risk-analyser/src/queues/workers/embedding.ts`](https://github.com/harshcodezzz/build-with-ai-hackathon/blob/main/risk-analyser/src/queues/workers/embedding.ts) (Embedding worker), [`frontend-ai-hackathon/src/App.jsx`](https://github.com/harshcodezzz/build-with-ai-hackathon/blob/main/frontend-ai-hackathon/src/App.jsx) (Portal routing), [`backend-ai-hackathon/src/api/router.ts`](https://github.com/harshcodezzz/build-with-ai-hackathon/blob/main/backend-ai-hackathon/src/api/router.ts) (API router)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_citizen["Citizen portal"]
  node_portal["Portal routing<br/>[App.jsx]"]
  node_auth_ui["Citizen auth<br/>[AuthContext.jsx]"]
  node_complaint_submit["Complaint submission"]
  node_audio_recorder["Audio recorder"]
  node_citizen_views["Citizen tracking<br/>[ComplaintsList.jsx]"]
  node_admin_views["Admin center<br/>[AdminDashboard.jsx]"]
  node_frontend_api["API client<br/>[api.js]"]
end

subgraph group_backend["Backend API"]
  node_backend_entry["API entry<br/>[index.ts]"]
  node_api_router["API router<br/>[router.ts]"]
  node_auth_api["Auth endpoints<br/>[auth.ts]"]
  node_auth_middleware["Token checks<br/>[auth.ts]"]
  node_complaint_api["Complaint endpoints<br/>[complain.ts]"]
  node_admin_api["Admin endpoints<br/>[admin.ts]"]
  node_upload_api["Audio upload URLs<br/>[storage.ts]"]
  node_audio_store[("Audio object storage<br/>[s3.ts]")]
end

subgraph group_transcript["Voice transcription"]
  node_transcript_api["Transcript service API<br/>[index.ts]"]
  node_transcript_jobs["Transcription jobs<br/>[queue.ts]"]
  node_transcribe["Speech transcription<br/>[transcribe.ts]"]
  node_translation["Translation<br/>[translate.ts]"]
  node_transcript_db[("Transcript job store<br/>[db.js]")]
end

subgraph group_analysis["Risk intelligence"]
  node_risk_entry["Risk service entry<br/>[index.ts]"]
  node_process_routes["Processing routes<br/>[process.ts]"]
  node_batch_service["Batch orchestration<br/>[batch.ts]"]
  node_batch_worker["Batch worker<br/>[batch.ts]"]
  node_embedding_worker["Embedding worker<br/>[embedding.ts]"]
  node_analysis_worker["Analysis worker<br/>[analysis.ts]"]
  node_risk_scoring["Risk scoring<br/>[aiRisk.ts]"]
  node_similarity["Issue clustering"]
  node_geo{{"Geo-sharding<br/>[geoshard.ts]"}}
  node_vector_store[("Vector search<br/>[pinecone.ts]")]
  node_pg_store[("Complaint database<br/>[postgres.ts]")]
  node_local_state[("Processing state<br/>[sqlite.ts]")]
  node_job_queue["Analysis queues<br/>[producers.ts]"]
end

node_citizen(("Citizen"))

node_citizen -->|"uses"| node_portal
node_portal -->|"provides auth"| node_auth_ui
node_portal -->|"routes to"| node_complaint_submit
node_portal -->|"routes to"| node_citizen_views
node_portal -->|"routes to"| node_admin_views
node_complaint_submit -->|"records through"| node_audio_recorder
node_auth_ui -->|"calls"| node_frontend_api
node_complaint_submit -->|"submits through"| node_frontend_api
node_frontend_api -.->|"sends requests"| node_backend_entry
node_backend_entry -->|"mounts"| node_api_router
node_api_router -->|"routes to"| node_auth_api
node_api_router -->|"routes to"| node_complaint_api
node_api_router -->|"routes to"| node_admin_api
node_api_router -->|"routes to"| node_upload_api
node_auth_api -->|"uses"| node_auth_middleware
node_upload_api -->|"checks tokens"| node_auth_middleware
node_upload_api -->|"requests upload URL"| node_audio_store
node_backend_entry -.->|"voice processing integration"| node_transcript_api
node_transcript_api -->|"queues jobs"| node_transcript_jobs
node_transcript_api -->|"runs transcription"| node_transcribe
node_transcript_api -->|"translates text"| node_translation
node_transcribe -->|"fetches audio"| node_audio_store
node_transcribe -->|"saves transcript"| node_transcript_db
node_transcript_jobs -->|"runs jobs"| node_transcribe
node_backend_entry -.->|"submits complaints"| node_risk_entry
node_risk_entry -->|"mounts routes"| node_process_routes
node_risk_entry -->|"starts worker"| node_batch_worker
node_risk_entry -->|"starts worker"| node_embedding_worker
node_risk_entry -->|"starts worker"| node_analysis_worker
node_process_routes -->|"invokes"| node_batch_service
node_batch_service -->|"enqueues work"| node_job_queue
node_batch_worker -.->|"dispatches embedding stage"| node_embedding_worker
node_embedding_worker -->|"reads complaints"| node_pg_store
node_embedding_worker -->|"resolves blocks"| node_geo
node_embedding_worker -->|"upserts vectors"| node_vector_store
node_embedding_worker -->|"updates status"| node_local_state
node_embedding_worker -->|"queues analysis"| node_analysis_worker
node_analysis_worker -.->|"scores complaints"| node_risk_scoring
node_analysis_worker -.->|"clusters issues"| node_similarity
node_risk_entry -->|"prepares index"| node_vector_store
node_risk_entry -->|"connects"| node_pg_store
node_risk_entry -->|"initializes"| node_local_state
node_risk_entry -.->|"status tracking"| node_citizen_views
node_risk_entry -.->|"risk results and leaderboard"| node_admin_views

click node_portal "https://github.com/harshcodezzz/build-with-ai-hackathon/blob/main/frontend-ai-hackathon/src/App.jsx"
click node_auth_ui "https://github.com/harshcodezzz/build-with-ai-hackathon/blob/main/frontend-ai-hackathon/src/context/AuthContext.jsx"
click node_complaint_submit "https://github.com/harshcodezzz/build-with-ai-hackathon/blob/main/frontend-ai-hackathon/src/pages/SubmitComplaint.jsx"
click node_audio_recorder "https://github.com/harshcodezzz/build-with-ai-hackathon/blob/main/frontend-ai-hackathon/src/hooks/useAudioRecorder.js"
click node_citizen_views "https://github.com/harshcodezzz/build-with-ai-hackathon/blob/main/frontend-ai-hackathon/src/pages/ComplaintsList.jsx"
click node_admin_views "https://github.com/harshcodezzz/build-with-ai-hackathon/blob/main/frontend-ai-hackathon/src/pages/admin/AdminDashboard.jsx"
click node_frontend_api "https://github.com/harshcodezzz/build-with-ai-hackathon/blob/main/frontend-ai-hackathon/src/utils/api.js"
click node_backend_entry "https://github.com/harshcodezzz/build-with-ai-hackathon/blob/main/backend-ai-hackathon/src/index.ts"
click node_api_router "https://github.com/harshcodezzz/build-with-ai-hackathon/blob/main/backend-ai-hackathon/src/api/router.ts"
click node_auth_api "https://github.com/harshcodezzz/build-with-ai-hackathon/blob/main/backend-ai-hackathon/src/api/auth.ts"
click node_auth_middleware "https://github.com/harshcodezzz/build-with-ai-hackathon/blob/main/backend-ai-hackathon/src/middlewares/auth.ts"
click node_complaint_api "https://github.com/harshcodezzz/build-with-ai-hackathon/blob/main/backend-ai-hackathon/src/api/complain.ts"
click node_admin_api "https://github.com/harshcodezzz/build-with-ai-hackathon/blob/main/backend-ai-hackathon/src/api/admin.ts"
click node_upload_api "https://github.com/harshcodezzz/build-with-ai-hackathon/blob/main/backend-ai-hackathon/src/api/storage.ts"
click node_audio_store "https://github.com/harshcodezzz/build-with-ai-hackathon/blob/main/backend-ai-hackathon/src/utils/s3.ts"
click node_transcript_api "https://github.com/harshcodezzz/build-with-ai-hackathon/blob/main/transcript-service/src/index.ts"
click node_transcript_jobs "https://github.com/harshcodezzz/build-with-ai-hackathon/blob/main/transcript-service/src/services/queue.ts"
click node_transcribe "https://github.com/harshcodezzz/build-with-ai-hackathon/blob/main/transcript-service/src/services/transcribe.ts"
click node_translation "https://github.com/harshcodezzz/build-with-ai-hackathon/blob/main/transcript-service/src/services/translate.ts"
click node_transcript_db "https://github.com/harshcodezzz/build-with-ai-hackathon/blob/main/transcript-service/db.js"
click node_risk_entry "https://github.com/harshcodezzz/build-with-ai-hackathon/blob/main/risk-analyser/src/index.ts"
click node_process_routes "https://github.com/harshcodezzz/build-with-ai-hackathon/blob/main/risk-analyser/src/routes/process.ts"
click node_batch_service "https://github.com/harshcodezzz/build-with-ai-hackathon/blob/main/risk-analyser/src/services/batch.ts"
click node_batch_worker "https://github.com/harshcodezzz/build-with-ai-hackathon/blob/main/risk-analyser/src/queues/workers/batch.ts"
click node_embedding_worker "https://github.com/harshcodezzz/build-with-ai-hackathon/blob/main/risk-analyser/src/queues/workers/embedding.ts"
click node_analysis_worker "https://github.com/harshcodezzz/build-with-ai-hackathon/blob/main/risk-analyser/src/queues/workers/analysis.ts"
click node_risk_scoring "https://github.com/harshcodezzz/build-with-ai-hackathon/blob/main/risk-analyser/src/math/aiRisk.ts"
click node_similarity "https://github.com/harshcodezzz/build-with-ai-hackathon/blob/main/risk-analyser/src/services/complainAnalysis.ts"
click node_geo "https://github.com/harshcodezzz/build-with-ai-hackathon/blob/main/risk-analyser/src/services/geoshard.ts"
click node_vector_store "https://github.com/harshcodezzz/build-with-ai-hackathon/blob/main/risk-analyser/src/services/pinecone.ts"
click node_pg_store "https://github.com/harshcodezzz/build-with-ai-hackathon/blob/main/risk-analyser/src/db/postgres.ts"
click node_local_state "https://github.com/harshcodezzz/build-with-ai-hackathon/blob/main/risk-analyser/src/db/sqlite.ts"
click node_job_queue "https://github.com/harshcodezzz/build-with-ai-hackathon/blob/main/risk-analyser/src/queues/producers.ts"

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_portal,node_auth_ui,node_complaint_submit,node_audio_recorder,node_citizen_views,node_admin_views,node_frontend_api toneBlue
class node_backend_entry,node_api_router,node_auth_api,node_auth_middleware,node_complaint_api,node_admin_api,node_upload_api,node_audio_store toneAmber
class node_transcript_api,node_transcript_jobs,node_transcribe,node_translation,node_transcript_db toneMint
class node_risk_entry,node_process_routes,node_batch_service,node_batch_worker,node_embedding_worker,node_analysis_worker,node_risk_scoring,node_similarity,node_geo,node_vector_store,node_pg_store,node_local_state,node_job_queue toneRose
class node_citizen toneIndigo
```

## Components

### Citizen portal

- [Portal routing](https://github.com/harshcodezzz/build-with-ai-hackathon/blob/main/frontend-ai-hackathon/src/App.jsx): `frontend-ai-hackathon/src/App.jsx`
- [Citizen auth](https://github.com/harshcodezzz/build-with-ai-hackathon/blob/main/frontend-ai-hackathon/src/context/AuthContext.jsx): `frontend-ai-hackathon/src/context/AuthContext.jsx`
- [Complaint submission](https://github.com/harshcodezzz/build-with-ai-hackathon/blob/main/frontend-ai-hackathon/src/pages/SubmitComplaint.jsx): `frontend-ai-hackathon/src/pages/SubmitComplaint.jsx`
- [Audio recorder](https://github.com/harshcodezzz/build-with-ai-hackathon/blob/main/frontend-ai-hackathon/src/hooks/useAudioRecorder.js): `frontend-ai-hackathon/src/hooks/useAudioRecorder.js`
- [Citizen tracking](https://github.com/harshcodezzz/build-with-ai-hackathon/blob/main/frontend-ai-hackathon/src/pages/ComplaintsList.jsx): `frontend-ai-hackathon/src/pages/ComplaintsList.jsx`
- [Admin center](https://github.com/harshcodezzz/build-with-ai-hackathon/blob/main/frontend-ai-hackathon/src/pages/admin/AdminDashboard.jsx): `frontend-ai-hackathon/src/pages/admin/AdminDashboard.jsx`
- [API client](https://github.com/harshcodezzz/build-with-ai-hackathon/blob/main/frontend-ai-hackathon/src/utils/api.js): `frontend-ai-hackathon/src/utils/api.js`

### Backend API

- [API entry](https://github.com/harshcodezzz/build-with-ai-hackathon/blob/main/backend-ai-hackathon/src/index.ts): `backend-ai-hackathon/src/index.ts`
- [API router](https://github.com/harshcodezzz/build-with-ai-hackathon/blob/main/backend-ai-hackathon/src/api/router.ts): `backend-ai-hackathon/src/api/router.ts`
- [Auth endpoints](https://github.com/harshcodezzz/build-with-ai-hackathon/blob/main/backend-ai-hackathon/src/api/auth.ts): `backend-ai-hackathon/src/api/auth.ts`
- [Token checks](https://github.com/harshcodezzz/build-with-ai-hackathon/blob/main/backend-ai-hackathon/src/middlewares/auth.ts): `backend-ai-hackathon/src/middlewares/auth.ts`
- [Complaint endpoints](https://github.com/harshcodezzz/build-with-ai-hackathon/blob/main/backend-ai-hackathon/src/api/complain.ts): `backend-ai-hackathon/src/api/complain.ts`
- [Admin endpoints](https://github.com/harshcodezzz/build-with-ai-hackathon/blob/main/backend-ai-hackathon/src/api/admin.ts): `backend-ai-hackathon/src/api/admin.ts`
- [Audio upload URLs](https://github.com/harshcodezzz/build-with-ai-hackathon/blob/main/backend-ai-hackathon/src/api/storage.ts): `backend-ai-hackathon/src/api/storage.ts`
- [Audio object storage](https://github.com/harshcodezzz/build-with-ai-hackathon/blob/main/backend-ai-hackathon/src/utils/s3.ts): `backend-ai-hackathon/src/utils/s3.ts`

### Voice transcription

- [Transcript service API](https://github.com/harshcodezzz/build-with-ai-hackathon/blob/main/transcript-service/src/index.ts): `transcript-service/src/index.ts`
- [Transcription jobs](https://github.com/harshcodezzz/build-with-ai-hackathon/blob/main/transcript-service/src/services/queue.ts): `transcript-service/src/services/queue.ts`
- [Speech transcription](https://github.com/harshcodezzz/build-with-ai-hackathon/blob/main/transcript-service/src/services/transcribe.ts): `transcript-service/src/services/transcribe.ts`
- [Translation](https://github.com/harshcodezzz/build-with-ai-hackathon/blob/main/transcript-service/src/services/translate.ts): `transcript-service/src/services/translate.ts`
- [Transcript job store](https://github.com/harshcodezzz/build-with-ai-hackathon/blob/main/transcript-service/db.js): `transcript-service/db.js`

### Risk intelligence

- [Risk service entry](https://github.com/harshcodezzz/build-with-ai-hackathon/blob/main/risk-analyser/src/index.ts): `risk-analyser/src/index.ts`
- [Processing routes](https://github.com/harshcodezzz/build-with-ai-hackathon/blob/main/risk-analyser/src/routes/process.ts): `risk-analyser/src/routes/process.ts`
- [Batch orchestration](https://github.com/harshcodezzz/build-with-ai-hackathon/blob/main/risk-analyser/src/services/batch.ts): `risk-analyser/src/services/batch.ts`
- [Batch worker](https://github.com/harshcodezzz/build-with-ai-hackathon/blob/main/risk-analyser/src/queues/workers/batch.ts): `risk-analyser/src/queues/workers/batch.ts`
- [Embedding worker](https://github.com/harshcodezzz/build-with-ai-hackathon/blob/main/risk-analyser/src/queues/workers/embedding.ts): `risk-analyser/src/queues/workers/embedding.ts`
- [Analysis worker](https://github.com/harshcodezzz/build-with-ai-hackathon/blob/main/risk-analyser/src/queues/workers/analysis.ts): `risk-analyser/src/queues/workers/analysis.ts`
- [Risk scoring](https://github.com/harshcodezzz/build-with-ai-hackathon/blob/main/risk-analyser/src/math/aiRisk.ts): `risk-analyser/src/math/aiRisk.ts`
- [Issue clustering](https://github.com/harshcodezzz/build-with-ai-hackathon/blob/main/risk-analyser/src/services/complainAnalysis.ts): `risk-analyser/src/services/complainAnalysis.ts`
- [Geo-sharding](https://github.com/harshcodezzz/build-with-ai-hackathon/blob/main/risk-analyser/src/services/geoshard.ts): `risk-analyser/src/services/geoshard.ts`
- [Vector search](https://github.com/harshcodezzz/build-with-ai-hackathon/blob/main/risk-analyser/src/services/pinecone.ts): `risk-analyser/src/services/pinecone.ts`
- [Complaint database](https://github.com/harshcodezzz/build-with-ai-hackathon/blob/main/risk-analyser/src/db/postgres.ts): `risk-analyser/src/db/postgres.ts`
- [Processing state](https://github.com/harshcodezzz/build-with-ai-hackathon/blob/main/risk-analyser/src/db/sqlite.ts): `risk-analyser/src/db/sqlite.ts`
- [Analysis queues](https://github.com/harshcodezzz/build-with-ai-hackathon/blob/main/risk-analyser/src/queues/producers.ts): `risk-analyser/src/queues/producers.ts`

### Other components

- **Citizen**

## Connections

- Citizen → Portal routing: uses (evidence: `README.md`)
- Portal routing → Citizen auth: provides auth (evidence: `frontend-ai-hackathon/src/App.jsx`)
- Portal routing → Complaint submission: routes to (evidence: `frontend-ai-hackathon/src/App.jsx`)
- Portal routing → Citizen tracking: routes to (evidence: `frontend-ai-hackathon/src/App.jsx`)
- Portal routing → Admin center: routes to (evidence: `frontend-ai-hackathon/src/App.jsx`)
- Complaint submission → Audio recorder: records through (evidence: `frontend-ai-hackathon/src/pages/SubmitComplaint.jsx`)
- Citizen auth → API client: calls (evidence: `frontend-ai-hackathon/src/context/AuthContext.jsx`)
- Complaint submission → API client: submits through (evidence: `frontend-ai-hackathon/src/pages/SubmitComplaint.jsx`)
- API client → API entry: sends requests (evidence: `README.md`)
- API entry → API router: mounts (evidence: `backend-ai-hackathon/src/index.ts`)
- API router → Auth endpoints: routes to (evidence: `backend-ai-hackathon/src/api/router.ts`)
- API router → Complaint endpoints: routes to (evidence: `backend-ai-hackathon/src/api/router.ts`)
- API router → Admin endpoints: routes to (evidence: `backend-ai-hackathon/src/api/router.ts`)
- API router → Audio upload URLs: routes to (evidence: `backend-ai-hackathon/src/api/router.ts`)
- Auth endpoints → Token checks: uses (evidence: `backend-ai-hackathon/src/api/auth.ts`)
- Audio upload URLs → Token checks: checks tokens (evidence: `backend-ai-hackathon/src/api/storage.ts`)
- Audio upload URLs → Audio object storage: requests upload URL (evidence: `backend-ai-hackathon/src/api/storage.ts`)
- API entry → Transcript service API: voice processing integration (evidence: `README.md`)
- Transcript service API → Transcription jobs: queues jobs (evidence: `transcript-service/src/index.ts`)
- Transcript service API → Speech transcription: runs transcription (evidence: `transcript-service/src/index.ts`)
- Transcript service API → Translation: translates text (evidence: `transcript-service/src/index.ts`)
- Speech transcription → Audio object storage: fetches audio (evidence: `transcript-service/src/services/transcribe.ts`)
- Speech transcription → Transcript job store: saves transcript (evidence: `transcript-service/src/services/transcribe.ts`)
- Transcription jobs → Speech transcription: runs jobs (evidence: `transcript-service/src/services/queue.ts`)
- API entry → Risk service entry: submits complaints (evidence: `README.md`)
- Risk service entry → Processing routes: mounts routes (evidence: `risk-analyser/src/index.ts`)
- Risk service entry → Batch worker: starts worker (evidence: `risk-analyser/src/index.ts`)
- Risk service entry → Embedding worker: starts worker (evidence: `risk-analyser/src/index.ts`)
- Risk service entry → Analysis worker: starts worker (evidence: `risk-analyser/src/index.ts`)
- Processing routes → Batch orchestration: invokes (evidence: `risk-analyser/src/routes/process.ts`)
- Batch orchestration → Analysis queues: enqueues work (evidence: `risk-analyser/src/services/batch.ts`)
- Batch worker → Embedding worker: dispatches embedding stage
- Embedding worker → Complaint database: reads complaints (evidence: `risk-analyser/src/queues/workers/embedding.ts`)
- Embedding worker → Geo-sharding: resolves blocks (evidence: `risk-analyser/src/queues/workers/embedding.ts`)
- Embedding worker → Vector search: upserts vectors (evidence: `risk-analyser/src/queues/workers/embedding.ts`)
- Embedding worker → Processing state: updates status (evidence: `risk-analyser/src/queues/workers/embedding.ts`)
- Embedding worker → Analysis worker: queues analysis (evidence: `risk-analyser/src/queues/workers/embedding.ts`)
- Analysis worker → Risk scoring: scores complaints
- Analysis worker → Issue clustering: clusters issues
- Risk service entry → Vector search: prepares index (evidence: `risk-analyser/src/index.ts`)
- Risk service entry → Complaint database: connects (evidence: `risk-analyser/src/index.ts`)
- Risk service entry → Processing state: initializes (evidence: `risk-analyser/src/index.ts`)
- Risk service entry → Citizen tracking: status tracking (evidence: `README.md`)
- Risk service entry → Admin center: risk results and leaderboard (evidence: `README.md`)
