aaditya02123/nagarsetu

1. Overall shape

- NagarSetu is a three-part system: a React frontend, a FastAPI backend, and a separate ML inference service.

- The backend is the main application boundary: it handles authentication, complaint persistence, admin operations, and orchestration of ML predictions.

2. Frontend subsystem

- NagarSetu-Frontend is a Vite-based React app organized around user-facing pages (Home, Login, Register, Report, UserDashboard) and a separate admin area under src/pages/admin.

- src/Api.js is the client-side API boundary to the backend.

- ProtectedRoute.jsx indicates route guarding for authenticated and role-based access, especially for admin pages.

3. Backend application structure

- NagarSetu-Backend/app is organized in a typical FastAPI layered layout:

- core for configuration, database wiring, and security

- models for SQLAlchemy entities

- schemas for Pydantic request/response contracts

- routers for HTTP endpoints

- services for business logic

- middleware for request-level auth enforcement

- main.py is the backend entrypoint.

4. Backend API boundaries

- The routers split responsibilities:

- auth.py for registration/login and token handling

- complaints.py for citizen complaint submission and complaint retrieval

- admin.py for admin-only complaint management and analytics-style access

- This separation suggests a clean API surface where frontend pages map to distinct backend resources.

5. Authentication and access control

- Security is JWT-based, with password hashing handled in core/security.py.

- middleware/auth.py implies request interception or dependency-based protection for privileged routes.

- The architecture supports at least two roles: citizen and admin, with admin functions isolated behind protected endpoints and UI routes.

6. Complaint domain model

- The main business object is the complaint, represented in both database models and API schemas (models/complaint.py, schemas/complaint.py).

- Complaints include user-submitted metadata such as title, description, category, location/city, image upload, status, department assignment, and likely AI-derived fields such as severity/priority.

7. Citizen complaint flow

- A citizen submits a report from the frontend, which sends data to the backend complaint endpoints.

- The backend stores complaint data in PostgreSQL, saves uploaded media under uploads/, and forwards the image to the ML inference layer for classification.

- The result comes back as issue category, confidence, severity, and suggested department, which are then persisted with the complaint record.

8. Admin complaint management flow

- Admin pages consume backend endpoints that expose the full complaint set and operational actions.

- Admins can update status, reassign departments, inspect citizen details, review complaint images, and track resolution progress.

- The admin dashboard also consumes aggregate data for overview cards, analytics, and departmental performance.

9. Machine learning boundary

- ML is not embedded directly into the frontend; it is a distinct inference subsystem.

- NagarSetu-Backend/inference_api.py serves as the runtime inference API, while NagarSetu-ML/ contains the training/evaluation/export pipeline.

- The model artifacts live in ml_models/ and models/, including ONNX and PyTorch exports plus class labels, which indicates the deployed inference path is optimized for serving rather than training.

10. Data storage and persistence

- PostgreSQL is the primary transactional store, accessed through SQLAlchemy and initialized via Alembic configuration (alembic.ini).

- seed.py suggests initial bootstrap data for users, admins, or reference records.

- Complaint images are stored on disk in an uploads/ hierarchy, so the system has both relational data and file-based media storage.

11. Configuration and environment

- Backend runtime configuration comes from .env, including database URL, JWT secret, token expiry, and frontend origin.

- The frontend also has its own .env, indicating the UI is configured separately from the API.

- This implies a decoupled deployment model where frontend, backend, and ML service can be started and scaled independently.

12. Training vs serving split

- NagarSetu-ML is the offline ML development environment: dataset download/organization, training, evaluation, export, and dataset verification scripts live there.

- The backend repository then consumes the exported model for production inference, which is a clear boundary between model development and application runtime.

13. Operational flow summary

- Browser → React app → FastAPI backend → PostgreSQL and uploads storage → ML inference API/model artifacts → backend persists enriched complaint → admin dashboard consumes the updated complaint state.

- That is the core architecture to capture in a diagram: presentation layer, application/API layer, ML service layer, and persistence layer.