# gtushar8055/civiclens architecture

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

- Interactive diagram: https://gitdiagram.com/gtushar8055/civiclens
- Repository: https://github.com/gtushar8055/civiclens

## Overview

1. **Overall shape**
   - CivicLens is a three-tier, service-separated system:
     - **React frontend** for user interaction
     - **Node/Express backend** for auth, persistence, and API orchestration
     - **FastAPI AI service** for NLP and image analysis
   - The backend and AI service are independently deployed and communicate over REST.

2. **Frontend boundary**
   - The `frontend/` app is a Vite-based React SPA.
   - It owns the user experience: landing, login/signup, complaint submission, analysis results, and complaint history.
   - Key route-level pages are `Home`, `Login`, `SignUp`, `ComplaintForm`, `Results`, and `History`.
   - Shared UI/state pieces include `Navbar`, `LoadingOverlay`, `ProtectedRoute`, and `ThemeContext`.

3. **Frontend data access**
   - All HTTP traffic is centralized through `frontend/src/services/api.js`.
   - The frontend talks to the backend only; it does not directly access MongoDB or the AI service.
   - Protected routes imply token-based session handling on the client side.

4. **Backend boundary**
   - The `backend/` app is an Express API server.
   - It is the main coordination layer between the UI, authentication, database, and AI processing.
   - `server.js` bootstraps the app, `config/db.js` connects to MongoDB Atlas, and `routes/` exposes auth and complaint endpoints.

5. **Authentication subsystem**
   - `authController.js`, `authRoutes.js`, and `authMiddleware.js` implement JWT-based authentication.
   - `userModel.js` stores user identity and credentials, while the middleware guards complaint/history operations.
   - The frontend’s `ProtectedRoute` mirrors this server-side boundary so only authenticated users can access sensitive screens.

6. **Complaint management subsystem**
   - `complaintController.js`, `complaintRoutes.js`, and `complaintModel.js` handle complaint creation and retrieval.
   - This is the persistence and history layer for user-submitted complaints and their AI-generated outputs.
   - Complaint history is user-scoped, which is why authentication is a core dependency.

7. **AI service boundary**
   - `ai-services/main.py` is a separate FastAPI microservice.
   - It performs the intelligence work: language detection, categorization, department recommendation, urgency estimation, entity extraction, complaint-letter generation, and image/evidence analysis.
   - The service is designed to return structured outputs suitable for storage and display by the backend/frontend.

8. **External AI dependency**
   - The AI service relies on the **Google Gemini API** and supports multiple API keys, which the README calls out as a failover/reliability mechanism.
   - Image handling uses Python tooling such as Pillow and multipart upload support.
   - This makes the AI service the only layer that depends on third-party generative AI infrastructure.

9. **Primary request flow**
   - A user submits a complaint in the frontend.
   - The request is authorized by JWT, sent to the backend, and then forwarded to the AI service for analysis.
   - The AI service returns structured intelligence; the backend stores the complaint and result in MongoDB Atlas.
   - The frontend then renders the analysis results and, later, retrieves them from the backend for history views.

10. **History and persistence**
   - MongoDB Atlas is the system of record for users and complaints.
   - The backend owns all reads/writes to the database, keeping the frontend and AI service stateless with respect to persistence.
   - This separation is important: the AI service computes, the backend persists, and the frontend presents.

11. **Deployment topology**
   - Frontend is deployed on **Vercel**.
   - Backend and AI service are deployed separately on **Render**.
   - MongoDB Atlas is an external managed database.
   - The deployment model matches the repo structure: independent services with REST-based integration.

12. **What matters for an architecture diagram**
   - Draw four major nodes: **Browser/React SPA**, **Express API**, **FastAPI AI service**, and **MongoDB Atlas**.
   - Add the external **Gemini API** behind the AI service.
   - Show JWT-protected flows from frontend to backend, backend-to-AI analysis calls, and backend-to-MongoDB persistence/history reads.

Main entry points: [`backend/controllers/complaintController.js`](https://github.com/gtushar8055/civiclens/blob/main/backend/controllers/complaintController.js) (Complaint Logic), [`backend/server.js`](https://github.com/gtushar8055/civiclens/blob/main/backend/server.js) (Express API), [`frontend/src/services/api.js`](https://github.com/gtushar8055/civiclens/blob/main/frontend/src/services/api.js) (API Client), [`backend/routes/complaintRoutes.js`](https://github.com/gtushar8055/civiclens/blob/main/backend/routes/complaintRoutes.js) (Complaint API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_frontend_app["React SPA<br/>vite-react<br/>[main.jsx]"]
  node_frontend_routes["Pages<br/>ui routes<br/>[Home.jsx]"]
  node_frontend_shared["Shared UI<br/>components<br/>[Navbar.jsx]"]
  node_frontend_api["API Client<br/>http client<br/>[api.js]"]
end

subgraph group_backend["Backend"]
  node_backend_server["Express API<br/>node server<br/>[server.js]"]
  node_backend_auth_routes["Auth API<br/>routes<br/>[authRoutes.js]"]
  node_backend_complaint_routes["Complaint API<br/>routes<br/>[complaintRoutes.js]"]
  node_backend_auth_controller["Auth Logic<br/>controller<br/>[authController.js]"]
  node_backend_complaint_controller["Complaint Logic<br/>controller"]
  node_backend_auth_middleware{{"Auth Guard<br/>middleware<br/>[authMiddleware.js]"}}
  node_backend_db["Mongo Connect<br/>db config<br/>[db.js]"]
  node_backend_user_model[("User Model<br/>mongoose model<br/>[userModel.js]")]
  node_backend_complaint_model[("Complaint Model<br/>mongoose model<br/>[complaintModel.js]")]
end

subgraph group_ai["AI Service"]
  node_ai_service["FastAPI AI<br/>python api<br/>[main.py]"]
end

subgraph group_external["External"]
  node_gemini_api(("Gemini API<br/>external ai"))
  node_mongodb_atlas[("MongoDB Atlas<br/>managed database")]
end

node_frontend_app -->|"renders"| node_frontend_routes
node_frontend_app -->|"uses"| node_frontend_shared
node_frontend_routes -->|"calls"| node_frontend_api
node_frontend_shared -.->|"guards requests"| node_frontend_api
node_frontend_api -->|"REST"| node_backend_server
node_backend_server -->|"mounts"| node_backend_auth_routes
node_backend_server -->|"mounts"| node_backend_complaint_routes
node_backend_auth_routes -->|"delegates"| node_backend_auth_controller
node_backend_complaint_routes -->|"protects"| node_backend_auth_middleware
node_backend_complaint_routes -->|"delegates"| node_backend_complaint_controller
node_backend_auth_controller -->|"reads/writes"| node_backend_user_model
node_backend_complaint_controller -->|"reads/writes"| node_backend_complaint_model
node_backend_server -->|"connects"| node_backend_db
node_backend_user_model -->|"stores"| node_mongodb_atlas
node_backend_complaint_model -->|"stores"| node_mongodb_atlas
node_backend_complaint_controller -->|"analyzes via REST"| node_ai_service
node_ai_service -->|"uses"| node_gemini_api
node_ai_service -->|"returns structured output"| node_backend_complaint_controller
node_backend_complaint_controller -.->|"responds to"| node_frontend_api

click node_frontend_app "https://github.com/gtushar8055/civiclens/blob/main/frontend/src/main.jsx"
click node_frontend_routes "https://github.com/gtushar8055/civiclens/blob/main/frontend/src/pages/Home.jsx"
click node_frontend_shared "https://github.com/gtushar8055/civiclens/blob/main/frontend/src/components/Navbar.jsx"
click node_frontend_api "https://github.com/gtushar8055/civiclens/blob/main/frontend/src/services/api.js"
click node_backend_server "https://github.com/gtushar8055/civiclens/blob/main/backend/server.js"
click node_backend_auth_routes "https://github.com/gtushar8055/civiclens/blob/main/backend/routes/authRoutes.js"
click node_backend_complaint_routes "https://github.com/gtushar8055/civiclens/blob/main/backend/routes/complaintRoutes.js"
click node_backend_auth_controller "https://github.com/gtushar8055/civiclens/blob/main/backend/controllers/authController.js"
click node_backend_complaint_controller "https://github.com/gtushar8055/civiclens/blob/main/backend/controllers/complaintController.js"
click node_backend_auth_middleware "https://github.com/gtushar8055/civiclens/blob/main/backend/middleware/authMiddleware.js"
click node_backend_db "https://github.com/gtushar8055/civiclens/blob/main/backend/config/db.js"
click node_backend_user_model "https://github.com/gtushar8055/civiclens/blob/main/backend/models/userModel.js"
click node_backend_complaint_model "https://github.com/gtushar8055/civiclens/blob/main/backend/models/complaintModel.js"
click node_ai_service "https://github.com/gtushar8055/civiclens/blob/main/ai-services/main.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_frontend_app,node_frontend_routes,node_frontend_shared,node_frontend_api toneBlue
class node_backend_server,node_backend_auth_routes,node_backend_complaint_routes,node_backend_auth_controller,node_backend_complaint_controller,node_backend_auth_middleware,node_backend_db,node_backend_user_model,node_backend_complaint_model toneAmber
class node_ai_service toneMint
class node_gemini_api,node_mongodb_atlas toneRose
```

## Components

### Frontend

Vite React SPA for user interaction

- [React SPA](https://github.com/gtushar8055/civiclens/blob/main/frontend/src/main.jsx): vite-react · Browser UI shell for CivicLens · `frontend/src/main.jsx`
- [Pages](https://github.com/gtushar8055/civiclens/blob/main/frontend/src/pages/Home.jsx): ui routes · Home, login, signup, complaint, results, and history screens · `frontend/src/pages/Home.jsx`
- [Shared UI](https://github.com/gtushar8055/civiclens/blob/main/frontend/src/components/Navbar.jsx): components · Navbar, loading overlay, protected route, and theme state · `frontend/src/components/Navbar.jsx`
- [API Client](https://github.com/gtushar8055/civiclens/blob/main/frontend/src/services/api.js): http client · Centralized frontend backend access · `frontend/src/services/api.js`

### Backend

Express API for auth, persistence, and orchestration

- [Express API](https://github.com/gtushar8055/civiclens/blob/main/backend/server.js): node server · Backend entrypoint and REST coordination layer · `backend/server.js`
- [Auth API](https://github.com/gtushar8055/civiclens/blob/main/backend/routes/authRoutes.js): routes · Login, signup, and session endpoints · `backend/routes/authRoutes.js`
- [Complaint API](https://github.com/gtushar8055/civiclens/blob/main/backend/routes/complaintRoutes.js): routes · Complaint submit and history endpoints · `backend/routes/complaintRoutes.js`
- [Auth Logic](https://github.com/gtushar8055/civiclens/blob/main/backend/controllers/authController.js): controller · JWT auth and user account handling · `backend/controllers/authController.js`
- [Complaint Logic](https://github.com/gtushar8055/civiclens/blob/main/backend/controllers/complaintController.js): controller · Complaint intake, retrieval, and AI orchestration · `backend/controllers/complaintController.js`
- [Auth Guard](https://github.com/gtushar8055/civiclens/blob/main/backend/middleware/authMiddleware.js): middleware · Protects user-scoped operations with JWT checks · `backend/middleware/authMiddleware.js`
- [Mongo Connect](https://github.com/gtushar8055/civiclens/blob/main/backend/config/db.js): db config · Database connection bootstrap · `backend/config/db.js`
- [User Model](https://github.com/gtushar8055/civiclens/blob/main/backend/models/userModel.js): mongoose model · User identity and credentials schema · `backend/models/userModel.js`
- [Complaint Model](https://github.com/gtushar8055/civiclens/blob/main/backend/models/complaintModel.js): mongoose model · Complaint and analysis persistence schema · `backend/models/complaintModel.js`

### AI Service

FastAPI microservice for NLP and image analysis

- [FastAPI AI](https://github.com/gtushar8055/civiclens/blob/main/ai-services/main.py): python api · Independent analysis service for complaints and evidence · `ai-services/main.py`

### External

Managed data and third-party AI dependencies

- **Gemini API**: external ai · Third-party generative AI dependency
- **MongoDB Atlas**: managed database · System of record for users and complaints

## Connections

- React SPA → Pages: renders · SPA hosts the user-facing screens
- React SPA → Shared UI: uses · Shared UI and auth-aware wrappers
- Pages → API Client: calls · Pages use the centralized API client
- Shared UI → API Client: guards requests · Protected route behavior depends on auth state and API session
- API Client → Express API: REST · Frontend talks only to the backend
- Express API → Auth API: mounts · Server exposes auth endpoints
- Express API → Complaint API: mounts · Server exposes complaint endpoints
- Auth API → Auth Logic: delegates · Route handlers forward to auth logic
- Complaint API → Auth Guard: protects · Complaint operations require JWT verification
- Complaint API → Complaint Logic: delegates · Route handlers forward to complaint logic
- Auth Logic → User Model: reads/writes · Auth logic persists users
- Complaint Logic → Complaint Model: reads/writes · Complaint logic persists complaints and results
- Express API → Mongo Connect: connects · Bootstraps MongoDB connection
- User Model → MongoDB Atlas: stores · User records live in managed MongoDB
- Complaint Model → MongoDB Atlas: stores · Complaint history and AI output live in managed MongoDB
- Complaint Logic → FastAPI AI: analyzes via REST · Backend forwards complaint content for NLP and image analysis
- FastAPI AI → Gemini API: uses · AI service relies on Gemini for generative analysis
- FastAPI AI → Complaint Logic: returns structured output · Analysis results are returned for storage and response
- Complaint Logic → API Client: responds to · Backend sends results back to the client