# harshs16/civix architecture

> Architecture diagram of the GitHub repository harshs16/civix, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/harshs16/civix
- Repository: https://github.com/harshs16/civix

## Overview

##### Project type and purpose
- This is a full-stack civic issue reporting web application (“Civix”) with a React-based frontend and a Node.js/Express backend, persisting data in PostgreSQL and integrating with Cloudinary for file storage. It provides separate citizen and admin flows, real-time status tracking, voting/upvoting, civic education modules, and an interactive frontend-only simulator.

##### File structure
- Top-level “backend” directory: Express.js app following MVC
- controllers/, models/, routes/
- middlewares/ for security, validation, file upload
- config/ holds db and swagger configuration
- utils/ for email, token handling, Cloudinary integration
- uploads/ stores local file artifacts
- Top-level “src” directory: React SPA
- Pages/ for each route
- components/ reusable UI pieces (auth, modals, voting widgets)
- hooks/, utils/, assets/
- index.jsx, App.jsx bootstrap the app
- public/: Static assets (index.html, manifest, GTFS data CSVs/JSONs)
- cypress/: E2E tests
- jest/vitest setup for unit/integration tests

##### README for additional insights
- Backend: PostgreSQL, JWT auth, multer file uploads, express-validator, Helmet, rate limiting, Swagger UI
- Frontend: React, Tailwind CSS, Leaflet for maps, dark mode toggle, localStorage persistence
- Two frontend-only modules: Civic Education, Civic Simulator

a. Main components
- Client (Browser/React SPA)
- API Gateway (Express.js server)
- Database (PostgreSQL)
- File Storage (Cloudinary + local uploads backup)
- Authentication (JWT service, token store)
- Caching (in-memory or contributors.json cache)
- Third-party services (Swagger UI, Stripe-like push notifications—future)
b. Relationships & interactions
- React SPA sends HTTP(S) requests (REST) to Express API
- API uses middlewares for CSRF, XSS sanitization, rate limiting, auth checks
- After auth, API processes business logic in controllers, queries PostgreSQL, and uses Cloudinary SDK to upload/download images
- API returns JSON payloads; React updates UI, stores tokens in localStorage, caches some data locally
- Module (Leaflet) fetches location data from public/gtfs or backend endpoints
- E2E tests hit public index.html, perform flows via API
c. Architectural patterns & principles
- MVC on backend (Models + Controllers + Routes)
- RESTful API design
- JWT-based stateless authentication, role-based access control
- Middleware pipeline for cross-cutting concerns (security, file handling)
- React component hierarchy + hooks for separation of concerns
- LocalStorage for client state persistence (dark mode, simulator XP)
d. Key technologies
- Frontend: React, Tailwind CSS, Leaflet.js, React Router
- Backend: Node.js, Express.js, Swagger, Helmet, express-validator, multer
- Database: PostgreSQL (with Sequelize or raw queries)
- Storage: Cloudinary, local file store
- Testing: Jest/Supertest, Vitest/RTL, Cypress

##### Detail
- Separate routes (/api/auth, /api/issues, /api/contributions, /api/profile)
- Swagger at /api-docs as a self-documenting API endpoint
- File upload flow: React → multer middleware → Cloudinary → DB
- Frontend-only modules (CivicEducation, CivicSimulator) connecting purely to localStorage/logic

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Frontend
    subgraph "Frontend (React SPA)" 
        direction TB
        subgraph "UI Components" 
            CivicEdu["CivicEducation.jsx"]:::frontend
            CivicSim["CivicSimulator.jsx"]:::frontend
            NewIssue["NewIssue.jsx"]:::frontend
            IssueDetail["IssueDetail.jsx"]:::frontend
            UserDash["UserDashboard.jsx"]:::frontend
            ProfilePage["Profile.jsx"]:::frontend
            AdminDash["AdminDashboard.jsx"]:::frontend
        end
        subgraph "Shared Components"
            LoginCmp["Login.jsx"]:::frontend
            SignupCmp["Signup.jsx"]:::frontend
            PrivateRoute["PrivateRoute.jsx"]:::frontend
            Navbar["Navbar.jsx"]:::frontend
            Footer["Footer.jsx"]:::frontend
            DarkToggle["DarkModeToggle.jsx"]:::frontend
            UserMap["UserMap.jsx"]:::frontend
            PollCreation["PollCreation.jsx"]:::frontend
            PollList["PollList.jsx"]:::frontend
            PollVoting["PollVoting.jsx"]:::frontend
            PollResults["PollResults.jsx"]:::frontend
            SubmissionModal["SubmissionConfirmation.jsx"]:::frontend
        end
        subgraph "Services" 
            APIClient["API Client"]:::frontend
            JWTService["Auth/Token Management"]:::frontend
            MapService["Leaflet Map Service"]:::frontend
        end
        subgraph "State & Hooks" 
            LocalStorage["LocalStorage"]:::frontend
            CSRFManager["csrfManager.js"]:::frontend
            SimulatorLogic["SimulatorLogic.js"]:::frontend
            Hooks["useProfileStatus.js & useToast.js"]:::frontend
        end
    end

    %% Backend
    subgraph "Backend (Express API)" 
        direction TB
        subgraph "API Layer (Routes)"
            AuthRoute["auth.js"]:::backend
            IssuesRoute["issues.js"]:::backend
            ContribRoute["contributions.js"]:::backend
            ProfileRoute["profileRoutes.js"]:::backend
        end
        subgraph "Middleware"
            Multer["multer.middleware.js"]:::backend
            Validate["validate.js"]:::backend
            CSRF["csrfProtection.js"]:::backend
            XSS["xssSanitizer.js"]:::backend
            ErrorHandler["errorHandler.js"]:::backend
        end
        subgraph "Business Logic (Controllers & Utils)"
            AuthCtrl["authController.js"]:::backend
            IssuesCtrl["issues.js"]:::backend
            ContrCtrl["contributor.js"]:::backend
            ProfileCtrl["profileControllers.js"]:::backend
            TokenUtil["token.js"]:::backend
            EmailUtil["sendEmail.js"]:::backend
            CloudUtil["cloudinary.js"]:::backend
        end
        subgraph "Data Layer"
            UserModel["userModel.js"]:::backend
            IssuesModel["issues.js"]:::backend
            DBConfig["db.js"]:::backend
        end
    end

    %% Database & Storage
    subgraph "Database & Storage"
        direction TB
        Postgres["PostgreSQL"]:::database
        LocalUpload["uploads/"]:::database
        ContributorsCache["contributors.json"]:::database
    end

    %% Third-Party & Testing
    subgraph "External Services & Testing"
        direction TB
        Cloudinary["Cloudinary"]:::external
        SwaggerUI["Swagger UI (/api-docs)"]:::external
        CypressTests["cypress/*.cy.js"]:::external
        JestTests["__tests__ & src/test"]:::external
    end

    %% Connections
    CivicEdu -->|uses| APIClient
    CivicSim -->|uses| SimulatorLogic
    NewIssue -->|calls| APIClient
    IssueDetail -->|calls| APIClient
    UserDash -->|calls| APIClient
    ProfilePage -->|calls| APIClient
    AdminDash -->|calls| APIClient
    LoginCmp -->|calls| APIClient
    SignupCmp -->|calls| APIClient
    PrivateRoute -->|uses| JWTService
    MapService -->|fetches GTFS| LocalUpload
    APIClient -->|REST| AuthRoute
    APIClient -->|REST| IssuesRoute
    APIClient -->|REST| ContribRoute
    APIClient -->|REST| ProfileRoute

    AuthRoute -->|uses| Multer
    AuthRoute -->|uses| Validate
    AuthRoute -->|pipeline| CSRF
    AuthRoute -->|pipeline| XSS
    AuthRoute --> AuthCtrl

    IssuesRoute -->|uses| Multer
    IssuesRoute -->|uses| Validate
    IssuesRoute --> IssuesCtrl

    ContribRoute -->|uses| Validate
    ContribRoute --> ContrCtrl

    ProfileRoute -->|uses| Validate
    ProfileRoute --> ProfileCtrl

    AuthCtrl -->|JWT| TokenUtil
    AuthCtrl -->|email| EmailUtil
    AuthCtrl --> UserModel

    IssuesCtrl --> IssuesModel
    IssuesCtrl -->|uploads| CloudUtil
    IssuesCtrl --> Postgres

    ContrCtrl --> ContributorsCache
    ContrCtrl --> UserModel

    ProfileCtrl --> UserModel

    UserModel --> DBConfig
    IssuesModel --> DBConfig
    DBConfig --> Postgres

    CloudUtil --> Cloudinary
    LocalUpload --> IssuesCtrl

    SwaggerUI -.->|docs| AuthRoute
    SwaggerUI -.-> IssuesRoute

    CypressTests -->|E2E flows| LocalUpload
    JestTests -->|unit/integration| AuthCtrl

    %% Click events
    click AuthRoute "https://github.com/harshs16/civix/blob/main/backend/routes/auth.js"
    click IssuesRoute "https://github.com/harshs16/civix/blob/main/backend/routes/issues.js"
    click ContribRoute "https://github.com/harshs16/civix/blob/main/backend/routes/contributions.js"
    click ProfileRoute "https://github.com/harshs16/civix/blob/main/backend/routes/profileRoutes.js"
    click AuthCtrl "https://github.com/harshs16/civix/blob/main/backend/controllers/authController.js"
    click IssuesCtrl "https://github.com/harshs16/civix/blob/main/backend/controllers/issues.js"
    click ContrCtrl "https://github.com/harshs16/civix/blob/main/backend/controllers/contributor.js"
    click ProfileCtrl "https://github.com/harshs16/civix/blob/main/backend/controllers/profileControllers.js"
    click UserModel "https://github.com/harshs16/civix/blob/main/backend/models/userModel.js"
    click IssuesModel "https://github.com/harshs16/civix/blob/main/backend/models/issues.js"
    click DBConfig "https://github.com/harshs16/civix/blob/main/backend/config/db.js"
    click CloudUtil "https://github.com/harshs16/civix/blob/main/backend/utils/cloudinary.js"
    click TokenUtil "https://github.com/harshs16/civix/blob/main/backend/utils/token.js"
    click EmailUtil "https://github.com/harshs16/civix/blob/main/backend/utils/sendEmail.js"
    click Multer "https://github.com/harshs16/civix/blob/main/backend/middlewares/multer.middleware.js"
    click Validate "https://github.com/harshs16/civix/blob/main/backend/middlewares/validate.js"
    click CSRF "https://github.com/harshs16/civix/blob/main/backend/middlewares/csrfProtection.js"
    click XSS "https://github.com/harshs16/civix/blob/main/backend/middlewares/xssSanitizer.js"
    click ErrorHandler "https://github.com/harshs16/civix/blob/main/backend/middlewares/errorHandler.js"
    click LocalUpload "https://github.com/harshs16/civix/tree/main/backend/uploads/"
    click ContributorsCache "https://github.com/harshs16/civix/blob/main/backend/cache/contributors.json"
    click CivicEdu "https://github.com/harshs16/civix/blob/main/src/Pages/CivicEducation.jsx"
    click CivicSim "https://github.com/harshs16/civix/blob/main/src/Pages/CivicSimulator.jsx"
    click NewIssue "https://github.com/harshs16/civix/blob/main/src/Pages/NewIssue.jsx"
    click IssueDetail "https://github.com/harshs16/civix/blob/main/src/Pages/IssueDetail.jsx"
    click UserDash "https://github.com/harshs16/civix/blob/main/src/Pages/UserDashboard.jsx"
    click ProfilePage "https://github.com/harshs16/civix/blob/main/src/Pages/Profile.jsx"
    click AdminDash "https://github.com/harshs16/civix/blob/main/src/Pages/AdminDashboard.jsx"
    click LoginCmp "https://github.com/harshs16/civix/blob/main/src/components/Login.jsx"
    click SignupCmp "https://github.com/harshs16/civix/blob/main/src/components/Signup.jsx"
    click PrivateRoute "https://github.com/harshs16/civix/blob/main/src/components/PrivateRoute.jsx"
    click Navbar "https://github.com/harshs16/civix/blob/main/src/components/Navbar.jsx"
    click Footer "https://github.com/harshs16/civix/blob/main/src/components/Footer.jsx"
    click DarkToggle "https://github.com/harshs16/civix/blob/main/src/DarkModeToggle.jsx"
    click UserMap "https://github.com/harshs16/civix/blob/main/src/Pages/UserMap.jsx"
    click PollCreation "https://github.com/harshs16/civix/blob/main/src/components/voting/PollCreation.jsx"
    click PollList "https://github.com/harshs16/civix/blob/main/src/components/voting/PollList.jsx"
    click PollVoting "https://github.com/harshs16/civix/blob/main/src/components/voting/PollVoting.jsx"
    click PollResults "https://github.com/harshs16/civix/blob/main/src/components/voting/PollResults.jsx"
    click SubmissionModal "https://github.com/harshs16/civix/blob/main/src/components/modals/SubmissionConfirmation.jsx"
    click SimulatorLogic "https://github.com/harshs16/civix/blob/main/src/utils/SimulatorLogic.js"
    click CSRFManager "https://github.com/harshs16/civix/blob/main/src/utils/csrfManager.js"
    click Hooks "https://github.com/harshs16/civix/blob/main/src/hooks/useProfileStatus.js"
    click Hooks "https://github.com/harshs16/civix/blob/main/src/hooks/useToast.js"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366d6,color:#0366d6;
    classDef backend fill:#E6FFDD,stroke:#28a745,color:#28a745;
    classDef database fill:#FFE8A1,stroke:#d18b00,color:#d18b00;
    classDef external fill:#F0DFFF,stroke:#6f42c1,color:#6f42c1;
    classDef service fill:#FFEBE6,stroke:#d73a49,color:#d73a49;
```
