# itanishqshelar/civicconnect architecture > Architecture diagram of the GitHub repository itanishqshelar/civicconnect, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source. - Interactive diagram: https://gitdiagram.com/itanishqshelar/civicconnect - Repository: https://github.com/itanishqshelar/civicconnect ## Overview CivicConnectAI is a citizen grievance platform: residents submit text and location, the backend classifies urgency, checks nearby complaints for semantic duplicates, routes by category and geography, and persists the result. Citizens can track complaints; authorities manage departmental queues and view analytics and hotspots. Voice intake is an alternate way to prepare a report before the normal location-and-submit flow. The README documents the clustering and dashboard capabilities; sampled source confirms the submission pipeline and ML endpoints, but not all analytics/dashboard wiring. Main entry points: [`frontend/src/lib/api.ts`](https://github.com/itanishqshelar/civicconnect/blob/main/frontend/src/lib/api.ts) (API Client), [`backend/src/server.js`](https://github.com/itanishqshelar/civicconnect/blob/main/backend/src/server.js) (Express API), [`ml-service/app/main.py`](https://github.com/itanishqshelar/civicconnect/blob/main/ml-service/app/main.py) (ML Service API), [`backend/src/services/complaintService.js`](https://github.com/itanishqshelar/civicconnect/blob/main/backend/src/services/complaintService.js) (Submission Pipeline) ## Diagram (Mermaid) ```mermaid flowchart TD subgraph group_frontend["Citizen and Authority UI"] node_portal["Portal
[page.tsx]"] node_submit["Submit Complaint
[page.tsx]"] node_voiceui["Voice Intake"] node_mycomplaints["My Complaints
[page.tsx]"] node_detail["Complaint Detail
[page.tsx]"] node_dashboard["Authority Dashboard
[page.tsx]"] node_maps["Maps and Charts
[ComplaintMap.tsx]"] node_frontendapi["API Client
[api.ts]"] node_auth["Supabase Auth
[AuthProvider.tsx]"] end subgraph group_backend["API and Grievance Workflow"] node_backend["Express API
[server.js]"] node_complaints["Complaint Endpoints"] node_pipeline["Submission Pipeline"] node_routing["Geo Routing
[routingService.js]"] node_analytics["Analytics Endpoints"] node_departments["Department Endpoints"] node_voiceapi["Voice Endpoint
[voiceController.js]"] node_gemini["Voice Assistant Client
[geminiClient.js]"] end subgraph group_ml["AI and Geospatial Analysis"] node_mlapi["ML Service API
[main.py]"] node_classification["Classification and Urgency
[classification.py]"] node_duplicates["Duplicate Detection
[duplicates.py]"] node_clustering["Hotspot Clustering
[clustering.py]"] end node_citizen(("Citizen")) node_authority(("Authority")) node_supabase[("Supabase Database")] node_groq{{"Groq AI"}} node_geminiservice{{"Gemini API"}} node_mapbox{{"Mapbox"}} node_citizen -->|"uses"| node_portal node_citizen -->|"enters report"| node_submit node_citizen -->|"speaks report"| node_voiceui node_authority -->|"views"| node_dashboard node_submit -->|"sends report"| node_frontendapi node_voiceui -->|"sends turns"| node_frontendapi node_mycomplaints -->|"requests records"| node_frontendapi node_detail -->|"requests detail"| node_frontendapi node_dashboard -->|"requests analytics"| node_frontendapi node_frontendapi -->|"calls API"| node_backend node_auth -->|"authenticates"| node_supabase node_backend -->|"dispatches requests"| node_complaints node_backend -->|"dispatches requests"| node_voiceapi node_backend -->|"dispatches requests"| node_analytics node_backend -->|"dispatches requests"| node_departments node_complaints -->|"submits complaint"| node_pipeline node_complaints -->|"reads and updates"| node_supabase node_pipeline -->|"classifies and checks"| node_mlapi node_pipeline -->|"gets candidates and department"| node_routing node_pipeline -->|"inserts complaint"| node_supabase node_routing -->|"queries geo data"| node_supabase node_voiceapi -->|"requests dialogue"| node_gemini node_gemini -.->|"calls"| node_geminiservice node_departments -->|"reads departments"| node_supabase node_analytics -->|"aggregates data"| node_supabase node_mlapi -->|"calls"| node_classification node_mlapi -->|"calls"| node_duplicates node_mlapi -->|"calls"| node_clustering node_classification -.->|"requests classification"| node_groq node_duplicates -.->|"requests similarity"| node_groq node_dashboard -->|"renders views"| node_maps node_maps -.->|"renders map"| node_mapbox node_mlapi -->|"clusters points"| node_clustering click node_portal "https://github.com/itanishqshelar/civicconnect/blob/main/frontend/src/app/page.tsx" click node_submit "https://github.com/itanishqshelar/civicconnect/blob/main/frontend/src/app/submit/page.tsx" click node_voiceui "https://github.com/itanishqshelar/civicconnect/blob/main/frontend/src/components/VoiceReportModal.tsx" click node_mycomplaints "https://github.com/itanishqshelar/civicconnect/blob/main/frontend/src/app/my-complaints/page.tsx" click node_detail "https://github.com/itanishqshelar/civicconnect/blob/main/frontend/src/app/complaints/%5Bid%5D/page.tsx" click node_dashboard "https://github.com/itanishqshelar/civicconnect/blob/main/frontend/src/app/dashboard/page.tsx" click node_maps "https://github.com/itanishqshelar/civicconnect/blob/main/frontend/src/components/ComplaintMap.tsx" click node_frontendapi "https://github.com/itanishqshelar/civicconnect/blob/main/frontend/src/lib/api.ts" click node_auth "https://github.com/itanishqshelar/civicconnect/blob/main/frontend/src/components/AuthProvider.tsx" click node_backend "https://github.com/itanishqshelar/civicconnect/blob/main/backend/src/server.js" click node_complaints "https://github.com/itanishqshelar/civicconnect/blob/main/backend/src/controllers/complaintsController.js" click node_pipeline "https://github.com/itanishqshelar/civicconnect/blob/main/backend/src/services/complaintService.js" click node_routing "https://github.com/itanishqshelar/civicconnect/blob/main/backend/src/services/routingService.js" click node_analytics "https://github.com/itanishqshelar/civicconnect/blob/main/backend/src/controllers/analyticsController.js" click node_departments "https://github.com/itanishqshelar/civicconnect/blob/main/backend/src/controllers/departmentsController.js" click node_voiceapi "https://github.com/itanishqshelar/civicconnect/blob/main/backend/src/controllers/voiceController.js" click node_gemini "https://github.com/itanishqshelar/civicconnect/blob/main/backend/src/services/geminiClient.js" click node_mlapi "https://github.com/itanishqshelar/civicconnect/blob/main/ml-service/app/main.py" click node_classification "https://github.com/itanishqshelar/civicconnect/blob/main/ml-service/app/classification.py" click node_duplicates "https://github.com/itanishqshelar/civicconnect/blob/main/ml-service/app/duplicates.py" click node_clustering "https://github.com/itanishqshelar/civicconnect/blob/main/ml-service/app/clustering.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_portal,node_submit,node_voiceui,node_mycomplaints,node_detail,node_dashboard,node_maps,node_frontendapi,node_auth toneBlue class node_backend,node_complaints,node_pipeline,node_routing,node_analytics,node_departments,node_voiceapi,node_gemini,node_supabase toneAmber class node_mlapi,node_classification,node_duplicates,node_clustering,node_geminiservice toneMint class node_citizen,node_authority,node_groq,node_mapbox toneIndigo ``` ## Components ### Citizen and Authority UI - [Portal](https://github.com/itanishqshelar/civicconnect/blob/main/frontend/src/app/page.tsx): `frontend/src/app/page.tsx` - [Submit Complaint](https://github.com/itanishqshelar/civicconnect/blob/main/frontend/src/app/submit/page.tsx): `frontend/src/app/submit/page.tsx` - [Voice Intake](https://github.com/itanishqshelar/civicconnect/blob/main/frontend/src/components/VoiceReportModal.tsx): `frontend/src/components/VoiceReportModal.tsx` - [My Complaints](https://github.com/itanishqshelar/civicconnect/blob/main/frontend/src/app/my-complaints/page.tsx): `frontend/src/app/my-complaints/page.tsx` - [Complaint Detail](https://github.com/itanishqshelar/civicconnect/blob/main/frontend/src/app/complaints/%5Bid%5D/page.tsx): `frontend/src/app/complaints/[id]/page.tsx` - [Authority Dashboard](https://github.com/itanishqshelar/civicconnect/blob/main/frontend/src/app/dashboard/page.tsx): `frontend/src/app/dashboard/page.tsx` - [Maps and Charts](https://github.com/itanishqshelar/civicconnect/blob/main/frontend/src/components/ComplaintMap.tsx): `frontend/src/components/ComplaintMap.tsx` - [API Client](https://github.com/itanishqshelar/civicconnect/blob/main/frontend/src/lib/api.ts): `frontend/src/lib/api.ts` - [Supabase Auth](https://github.com/itanishqshelar/civicconnect/blob/main/frontend/src/components/AuthProvider.tsx): `frontend/src/components/AuthProvider.tsx` ### API and Grievance Workflow - [Express API](https://github.com/itanishqshelar/civicconnect/blob/main/backend/src/server.js): `backend/src/server.js` - [Complaint Endpoints](https://github.com/itanishqshelar/civicconnect/blob/main/backend/src/controllers/complaintsController.js): `backend/src/controllers/complaintsController.js` - [Submission Pipeline](https://github.com/itanishqshelar/civicconnect/blob/main/backend/src/services/complaintService.js): `backend/src/services/complaintService.js` - [Geo Routing](https://github.com/itanishqshelar/civicconnect/blob/main/backend/src/services/routingService.js): `backend/src/services/routingService.js` - [Analytics Endpoints](https://github.com/itanishqshelar/civicconnect/blob/main/backend/src/controllers/analyticsController.js): `backend/src/controllers/analyticsController.js` - [Department Endpoints](https://github.com/itanishqshelar/civicconnect/blob/main/backend/src/controllers/departmentsController.js): `backend/src/controllers/departmentsController.js` - [Voice Endpoint](https://github.com/itanishqshelar/civicconnect/blob/main/backend/src/controllers/voiceController.js): `backend/src/controllers/voiceController.js` - [Voice Assistant Client](https://github.com/itanishqshelar/civicconnect/blob/main/backend/src/services/geminiClient.js): `backend/src/services/geminiClient.js` ### AI and Geospatial Analysis - [ML Service API](https://github.com/itanishqshelar/civicconnect/blob/main/ml-service/app/main.py): `ml-service/app/main.py` - [Classification and Urgency](https://github.com/itanishqshelar/civicconnect/blob/main/ml-service/app/classification.py): `ml-service/app/classification.py` - [Duplicate Detection](https://github.com/itanishqshelar/civicconnect/blob/main/ml-service/app/duplicates.py): `ml-service/app/duplicates.py` - [Hotspot Clustering](https://github.com/itanishqshelar/civicconnect/blob/main/ml-service/app/clustering.py): `ml-service/app/clustering.py` ### Other components - **Citizen** - **Authority** - **Supabase Database** - **Groq AI** - **Gemini API** - **Mapbox** ## Connections - Citizen → Portal: uses - Citizen → Submit Complaint: enters report - Citizen → Voice Intake: speaks report - Authority → Authority Dashboard: views - Submit Complaint → API Client: sends report - Voice Intake → API Client: sends turns - My Complaints → API Client: requests records - Complaint Detail → API Client: requests detail - Authority Dashboard → API Client: requests analytics - API Client → Express API: calls API - Supabase Auth → Supabase Database: authenticates - Express API → Complaint Endpoints: dispatches requests - Express API → Voice Endpoint: dispatches requests - Express API → Analytics Endpoints: dispatches requests - Express API → Department Endpoints: dispatches requests - Complaint Endpoints → Submission Pipeline: submits complaint - Complaint Endpoints → Supabase Database: reads and updates - Submission Pipeline → ML Service API: classifies and checks - Submission Pipeline → Geo Routing: gets candidates and department - Submission Pipeline → Supabase Database: inserts complaint - Geo Routing → Supabase Database: queries geo data - Voice Endpoint → Voice Assistant Client: requests dialogue - Voice Assistant Client → Gemini API: calls - Department Endpoints → Supabase Database: reads departments - Analytics Endpoints → Supabase Database: aggregates data - ML Service API → Classification and Urgency: calls - ML Service API → Duplicate Detection: calls - ML Service API → Hotspot Clustering: calls - Classification and Urgency → Groq AI: requests classification - Duplicate Detection → Groq AI: requests similarity - Authority Dashboard → Maps and Charts: renders views - Maps and Charts → Mapbox: renders map - ML Service API → Hotspot Clustering: clusters points