# janani-bn/civicfix architecture

> Architecture diagram of the GitHub repository janani-bn/civicfix, 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/janani-bn/civicfix
- Repository: https://github.com/janani-bn/civicfix

## Overview

CivicFix is a civic-issue reporting and resolution application. Citizens can report and track local problems, while maps, a public feed, AI assistance, volunteers, and administrators support community response and resolution. The frontend routes users to these capabilities and shares authentication state; the backend exposes API routes for complaints, accounts, comments, volunteers, and AI. Source-index references and excerpts support the backend call edges shown; some frontend-to-backend request details and unsampled feature wiring are not visible, so those links are omitted.

Main entry points: [`src/App.jsx`](https://github.com/janani-bn/civicfix/blob/main/src/App.jsx) (Application shell), [`src/services/api.js`](https://github.com/janani-bn/civicfix/blob/main/src/services/api.js) (API configuration), [`backend/server.js`](https://github.com/janani-bn/civicfix/blob/main/backend/server.js) (API server), [`backend/src/models/User.js`](https://github.com/janani-bn/civicfix/blob/main/backend/src/models/User.js) (User records)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_citizen["Citizen experience"]
  node_app["Application shell<br/>[App.jsx]"]
  node_report["Issue reporting"]
  node_tracking["Complaint tracking<br/>[TrackComplaint.jsx]"]
  node_voice["Voice guide"]
  node_welcome["Welcome guidance<br/>[WelcomeOverlay.jsx]"]
  node_authui["Authentication UI<br/>[Login.jsx]"]
end

subgraph group_community["Community response"]
  node_feed["Live issue feed<br/>[LiveFeed.jsx]"]
  node_map["Issue map<br/>[LiveMap.jsx]"]
  node_maplogic["Map logic<br/>[liveMapLogic.js]"]
  node_myissues["My complaints<br/>[MyComplaints.jsx]"]
  node_nearby["Nearby issues"]
  node_adminui["Admin dashboard<br/>[AdminDashboard.jsx]"]
  node_volunteerui["Volunteer dashboard"]
  node_comments["Community comments<br/>[comments.js]"]
  node_volunteers["Volunteer requests"]
  node_volunteer_routes["Volunteer routes<br/>[volunteers.js]"]
end

subgraph group_backend["API and workflows"]
  node_api["API configuration<br/>[api.js]"]
  node_server["API server<br/>[server.js]"]
  node_complaint_routes["Complaint routes<br/>[complaints.js]"]
  node_complaint_workflow["Complaint workflow"]
  node_department["Department routing"]
  node_complaint_model["Complaint records<br/>[Complaint.js]"]
end

subgraph group_identity["Identity and persistence"]
  node_authstate["Authentication state<br/>[AuthContext.jsx]"]
  node_auth_routes["Account routes<br/>[auth.js]"]
  node_auth_workflow["Account workflow<br/>[authController.js]"]
  node_auth_middleware["Token and role checks<br/>[auth.js]"]
  node_user_model["User records<br/>[User.js]"]
  node_database[("SQLite database<br/>[database.js]")]
end

subgraph group_assistance["AI assistance"]
  node_aiui["AI chatbot<br/>[LiveChatbot.jsx]"]
  node_ai_routes["AI routes<br/>[ai.js]"]
  node_ai_workflow["AI request handling<br/>[aiController.js]"]
  node_gemini["Gemini service<br/>[geminiService.js]"]
end

node_citizen_actor(("Citizen"))
node_gemini_service{{"Google Gemini"}}

node_citizen_actor -->|"uses"| node_app
node_app -->|"opens"| node_report
node_app -->|"routes to"| node_tracking
node_app -->|"routes to"| node_feed
node_app -->|"routes to"| node_map
node_app -->|"routes to"| node_adminui
node_app -->|"routes to"| node_volunteerui
node_app -->|"renders"| node_voice
node_app -->|"renders"| node_welcome
node_app -->|"renders"| node_aiui
node_app -->|"routes to"| node_myissues
node_app -->|"routes to"| node_nearby
node_app -->|"routes to"| node_authui
node_report -->|"uses configuration"| node_api
node_tracking -->|"uses configuration"| node_api
node_feed -->|"uses configuration"| node_api
node_map -->|"uses configuration"| node_api
node_map -->|"uses"| node_maplogic
node_adminui -->|"uses configuration"| node_api
node_volunteerui -->|"uses configuration"| node_api
node_report -->|"reads auth state"| node_authstate
node_authstate -->|"uses configuration"| node_api
node_server -->|"mounts"| node_complaint_routes
node_server -->|"mounts"| node_auth_routes
node_server -->|"mounts"| node_comments
node_server -->|"mounts"| node_volunteer_routes
node_server -->|"mounts"| node_ai_routes
node_complaint_routes -->|"dispatches"| node_complaint_workflow
node_complaint_workflow -->|"reads and writes"| node_complaint_model
node_complaint_workflow -->|"routes issue"| node_department
node_complaint_model -->|"queries"| node_database
node_auth_routes -->|"dispatches"| node_auth_workflow
node_auth_workflow -->|"reads and writes"| node_user_model
node_auth_workflow -->|"uses token config"| node_auth_middleware
node_auth_middleware -->|"checks roles"| node_user_model
node_user_model -->|"queries"| node_database
node_volunteer_routes -->|"dispatches"| node_volunteers
node_volunteers -->|"reads user"| node_user_model
node_ai_routes -->|"dispatches"| node_ai_workflow
node_ai_workflow -->|"requests AI"| node_gemini
node_gemini -.->|"calls"| node_gemini_service

click node_app "https://github.com/janani-bn/civicfix/blob/main/src/App.jsx"
click node_report "https://github.com/janani-bn/civicfix/blob/main/src/components/ReportIssueModal.jsx"
click node_tracking "https://github.com/janani-bn/civicfix/blob/main/src/components/TrackComplaint.jsx"
click node_voice "https://github.com/janani-bn/civicfix/blob/main/src/components/VoiceGuideAssistance.jsx"
click node_welcome "https://github.com/janani-bn/civicfix/blob/main/src/components/WelcomeOverlay.jsx"
click node_authui "https://github.com/janani-bn/civicfix/blob/main/src/components/Login.jsx"
click node_authstate "https://github.com/janani-bn/civicfix/blob/main/src/context/AuthContext.jsx"
click node_api "https://github.com/janani-bn/civicfix/blob/main/src/services/api.js"
click node_feed "https://github.com/janani-bn/civicfix/blob/main/src/components/LiveFeed.jsx"
click node_map "https://github.com/janani-bn/civicfix/blob/main/src/components/LiveMap.jsx"
click node_maplogic "https://github.com/janani-bn/civicfix/blob/main/src/utils/liveMapLogic.js"
click node_myissues "https://github.com/janani-bn/civicfix/blob/main/src/components/MyComplaints.jsx"
click node_nearby "https://github.com/janani-bn/civicfix/blob/main/src/components/NearbyComplaints.jsx"
click node_adminui "https://github.com/janani-bn/civicfix/blob/main/src/components/AdminDashboard.jsx"
click node_volunteerui "https://github.com/janani-bn/civicfix/blob/main/src/components/VolunteerDashboard.jsx"
click node_server "https://github.com/janani-bn/civicfix/blob/main/backend/server.js"
click node_complaint_routes "https://github.com/janani-bn/civicfix/blob/main/backend/src/routes/complaints.js"
click node_complaint_workflow "https://github.com/janani-bn/civicfix/blob/main/backend/src/controllers/complaintController.js"
click node_department "https://github.com/janani-bn/civicfix/blob/main/backend/src/utils/departmentRouter.js"
click node_auth_routes "https://github.com/janani-bn/civicfix/blob/main/backend/src/routes/auth.js"
click node_auth_workflow "https://github.com/janani-bn/civicfix/blob/main/backend/src/controllers/authController.js"
click node_auth_middleware "https://github.com/janani-bn/civicfix/blob/main/backend/src/middleware/auth.js"
click node_user_model "https://github.com/janani-bn/civicfix/blob/main/backend/src/models/User.js"
click node_complaint_model "https://github.com/janani-bn/civicfix/blob/main/backend/src/models/Complaint.js"
click node_database "https://github.com/janani-bn/civicfix/blob/main/backend/src/config/database.js"
click node_comments "https://github.com/janani-bn/civicfix/blob/main/backend/src/routes/comments.js"
click node_volunteers "https://github.com/janani-bn/civicfix/blob/main/backend/src/controllers/volunteerController.js"
click node_volunteer_routes "https://github.com/janani-bn/civicfix/blob/main/backend/src/routes/volunteers.js"
click node_aiui "https://github.com/janani-bn/civicfix/blob/main/src/components/LiveChatbot.jsx"
click node_ai_routes "https://github.com/janani-bn/civicfix/blob/main/backend/src/routes/ai.js"
click node_ai_workflow "https://github.com/janani-bn/civicfix/blob/main/backend/src/controllers/aiController.js"
click node_gemini "https://github.com/janani-bn/civicfix/blob/main/backend/src/services/geminiService.js"

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_report,node_tracking,node_voice,node_welcome,node_authui toneBlue
class node_feed,node_map,node_maplogic,node_myissues,node_nearby,node_adminui,node_volunteerui,node_comments,node_volunteers,node_volunteer_routes toneAmber
class node_api,node_server,node_complaint_routes,node_complaint_workflow,node_department,node_complaint_model toneMint
class node_authstate,node_auth_routes,node_auth_workflow,node_auth_middleware,node_user_model,node_database toneRose
class node_aiui,node_ai_routes,node_ai_workflow,node_gemini,node_citizen_actor,node_gemini_service toneIndigo
```

## Components

### Citizen experience

- [Application shell](https://github.com/janani-bn/civicfix/blob/main/src/App.jsx): `src/App.jsx`
- [Issue reporting](https://github.com/janani-bn/civicfix/blob/main/src/components/ReportIssueModal.jsx): `src/components/ReportIssueModal.jsx`
- [Complaint tracking](https://github.com/janani-bn/civicfix/blob/main/src/components/TrackComplaint.jsx): `src/components/TrackComplaint.jsx`
- [Voice guide](https://github.com/janani-bn/civicfix/blob/main/src/components/VoiceGuideAssistance.jsx): `src/components/VoiceGuideAssistance.jsx`
- [Welcome guidance](https://github.com/janani-bn/civicfix/blob/main/src/components/WelcomeOverlay.jsx): `src/components/WelcomeOverlay.jsx`
- [Authentication UI](https://github.com/janani-bn/civicfix/blob/main/src/components/Login.jsx): `src/components/Login.jsx`

### Community response

- [Live issue feed](https://github.com/janani-bn/civicfix/blob/main/src/components/LiveFeed.jsx): `src/components/LiveFeed.jsx`
- [Issue map](https://github.com/janani-bn/civicfix/blob/main/src/components/LiveMap.jsx): `src/components/LiveMap.jsx`
- [Map logic](https://github.com/janani-bn/civicfix/blob/main/src/utils/liveMapLogic.js): `src/utils/liveMapLogic.js`
- [My complaints](https://github.com/janani-bn/civicfix/blob/main/src/components/MyComplaints.jsx): `src/components/MyComplaints.jsx`
- [Nearby issues](https://github.com/janani-bn/civicfix/blob/main/src/components/NearbyComplaints.jsx): `src/components/NearbyComplaints.jsx`
- [Admin dashboard](https://github.com/janani-bn/civicfix/blob/main/src/components/AdminDashboard.jsx): `src/components/AdminDashboard.jsx`
- [Volunteer dashboard](https://github.com/janani-bn/civicfix/blob/main/src/components/VolunteerDashboard.jsx): `src/components/VolunteerDashboard.jsx`
- [Community comments](https://github.com/janani-bn/civicfix/blob/main/backend/src/routes/comments.js): `backend/src/routes/comments.js`
- [Volunteer requests](https://github.com/janani-bn/civicfix/blob/main/backend/src/controllers/volunteerController.js): `backend/src/controllers/volunteerController.js`
- [Volunteer routes](https://github.com/janani-bn/civicfix/blob/main/backend/src/routes/volunteers.js): `backend/src/routes/volunteers.js`

### API and workflows

- [API configuration](https://github.com/janani-bn/civicfix/blob/main/src/services/api.js): `src/services/api.js`
- [API server](https://github.com/janani-bn/civicfix/blob/main/backend/server.js): `backend/server.js`
- [Complaint routes](https://github.com/janani-bn/civicfix/blob/main/backend/src/routes/complaints.js): `backend/src/routes/complaints.js`
- [Complaint workflow](https://github.com/janani-bn/civicfix/blob/main/backend/src/controllers/complaintController.js): `backend/src/controllers/complaintController.js`
- [Department routing](https://github.com/janani-bn/civicfix/blob/main/backend/src/utils/departmentRouter.js): `backend/src/utils/departmentRouter.js`
- [Complaint records](https://github.com/janani-bn/civicfix/blob/main/backend/src/models/Complaint.js): `backend/src/models/Complaint.js`

### Identity and persistence

- [Authentication state](https://github.com/janani-bn/civicfix/blob/main/src/context/AuthContext.jsx): `src/context/AuthContext.jsx`
- [Account routes](https://github.com/janani-bn/civicfix/blob/main/backend/src/routes/auth.js): `backend/src/routes/auth.js`
- [Account workflow](https://github.com/janani-bn/civicfix/blob/main/backend/src/controllers/authController.js): `backend/src/controllers/authController.js`
- [Token and role checks](https://github.com/janani-bn/civicfix/blob/main/backend/src/middleware/auth.js): `backend/src/middleware/auth.js`
- [User records](https://github.com/janani-bn/civicfix/blob/main/backend/src/models/User.js): `backend/src/models/User.js`
- [SQLite database](https://github.com/janani-bn/civicfix/blob/main/backend/src/config/database.js): `backend/src/config/database.js`

### AI assistance

- [AI chatbot](https://github.com/janani-bn/civicfix/blob/main/src/components/LiveChatbot.jsx): `src/components/LiveChatbot.jsx`
- [AI routes](https://github.com/janani-bn/civicfix/blob/main/backend/src/routes/ai.js): `backend/src/routes/ai.js`
- [AI request handling](https://github.com/janani-bn/civicfix/blob/main/backend/src/controllers/aiController.js): `backend/src/controllers/aiController.js`
- [Gemini service](https://github.com/janani-bn/civicfix/blob/main/backend/src/services/geminiService.js): `backend/src/services/geminiService.js`

### Other components

- **Citizen**
- **Google Gemini**

## Connections

- Citizen → Application shell: uses (evidence: `src/App.jsx`)
- Application shell → Issue reporting: opens (evidence: `src/App.jsx`)
- Application shell → Complaint tracking: routes to (evidence: `src/App.jsx`)
- Application shell → Live issue feed: routes to (evidence: `src/App.jsx`)
- Application shell → Issue map: routes to (evidence: `src/App.jsx`)
- Application shell → Admin dashboard: routes to (evidence: `src/App.jsx`)
- Application shell → Volunteer dashboard: routes to (evidence: `src/App.jsx`)
- Application shell → Voice guide: renders (evidence: `src/App.jsx`)
- Application shell → Welcome guidance: renders (evidence: `src/App.jsx`)
- Application shell → AI chatbot: renders (evidence: `src/App.jsx`)
- Application shell → My complaints: routes to (evidence: `src/App.jsx`)
- Application shell → Nearby issues: routes to (evidence: `src/App.jsx`)
- Application shell → Authentication UI: routes to (evidence: `src/App.jsx`)
- Issue reporting → API configuration: uses configuration (evidence: `src/components/ReportIssueModal.jsx`)
- Complaint tracking → API configuration: uses configuration (evidence: `src/components/TrackComplaint.jsx`)
- Live issue feed → API configuration: uses configuration (evidence: `src/components/LiveFeed.jsx`)
- Issue map → API configuration: uses configuration (evidence: `src/components/LiveMap.jsx`)
- Issue map → Map logic: uses (evidence: `src/components/LiveMap.jsx`)
- Admin dashboard → API configuration: uses configuration (evidence: `src/components/AdminDashboard.jsx`)
- Volunteer dashboard → API configuration: uses configuration (evidence: `src/components/VolunteerDashboard.jsx`)
- Issue reporting → Authentication state: reads auth state (evidence: `src/components/ReportIssueModal.jsx`)
- Authentication state → API configuration: uses configuration (evidence: `src/context/AuthContext.jsx`)
- API server → Complaint routes: mounts (evidence: `backend/server.js`)
- API server → Account routes: mounts (evidence: `backend/server.js`)
- API server → Community comments: mounts (evidence: `backend/server.js`)
- API server → Volunteer routes: mounts (evidence: `backend/server.js`)
- API server → AI routes: mounts (evidence: `backend/server.js`)
- Complaint routes → Complaint workflow: dispatches (evidence: `backend/src/routes/complaints.js`)
- Complaint workflow → Complaint records: reads and writes (evidence: `backend/src/controllers/complaintController.js`)
- Complaint workflow → Department routing: routes issue (evidence: `backend/src/controllers/complaintController.js`)
- Complaint records → SQLite database: queries (evidence: `backend/src/models/Complaint.js`)
- Account routes → Account workflow: dispatches (evidence: `backend/src/routes/auth.js`)
- Account workflow → User records: reads and writes (evidence: `backend/src/controllers/authController.js`)
- Account workflow → Token and role checks: uses token config (evidence: `backend/src/controllers/authController.js`)
- Token and role checks → User records: checks roles (evidence: `backend/src/middleware/auth.js`)
- User records → SQLite database: queries (evidence: `backend/src/models/User.js`)
- Volunteer routes → Volunteer requests: dispatches (evidence: `backend/src/routes/volunteers.js`)
- Volunteer requests → User records: reads user (evidence: `backend/src/controllers/volunteerController.js`)
- AI routes → AI request handling: dispatches (evidence: `backend/src/routes/ai.js`)
- AI request handling → Gemini service: requests AI (evidence: `backend/src/controllers/aiController.js`)
- Gemini service → Google Gemini: calls
