How gtushar8055/civiclens works
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: complaintController.js Complaint Logic · server.js Express API · api.js API Client · complaintRoutes.js Complaint API
Components 16
Frontend
Vite React SPA for user interaction
- React SPA · Browser UI shell for CivicLens
frontend/src/main.jsx - Pages · Home, login, signup, complaint, results, and history screens
frontend/src/pages/Home.jsx - Shared UI · Navbar, loading overlay, protected route, and theme state
frontend/src/components/Navbar.jsx - API Client · Centralized frontend backend access
frontend/src/services/api.js
Backend
Express API for auth, persistence, and orchestration
- Express API · Backend entrypoint and REST coordination layer
backend/server.js - Auth API · Login, signup, and session endpoints
backend/routes/authRoutes.js - Complaint API · Complaint submit and history endpoints
backend/routes/complaintRoutes.js - Auth Logic · JWT auth and user account handling
backend/controllers/authController.js - Complaint Logic · Complaint intake, retrieval, and AI orchestration
backend/controllers/complaintController.js - Auth Guard · Protects user-scoped operations with JWT checks
backend/middleware/authMiddleware.js - Mongo Connect · Database connection bootstrap
backend/config/db.js - User Model · User identity and credentials schema
backend/models/userModel.js - Complaint Model · Complaint and analysis persistence schema
backend/models/complaintModel.js
AI Service
FastAPI microservice for NLP and image analysis
- FastAPI AI · Independent analysis service for complaints and evidence
ai-services/main.py
External
Managed data and third-party AI dependencies
- Gemini API · Third-party generative AI dependency
- MongoDB Atlas · System of record for users and complaints
Connections 19
- 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