# hirtikmalvi/civicvoice architecture

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

- Interactive diagram: https://gitdiagram.com/hirtikmalvi/civicvoice
- Repository: https://github.com/hirtikmalvi/civicvoice

## Overview

##### Project Type and Purpose
- CivicVoice is a full‑stack web application that allows citizens to create and track complaints, authorities to manage them, and admins to oversee the system.
- The backend is a Node.js/Express REST API (TypeScript, Prisma ORM, JWT auth, Cloudinary media storage).
- The frontend is a React/TypeScript single‑page application (SPA) deployed on Vercel.

##### File Structure
- Top‑level directories: “backend” and “frontend” indicate a clear separation of concerns.
- Backend folders—controllers, services, routes, middlewares, utils—reflect a layered MVC‑style architecture.
- The presence of prisma/schema.prisma shows a relational database (e.g., PostgreSQL).
- Config/cloudinary.ts and utils/uploadToCloudinary.ts indicate integration with external media storage.
- Frontend folders—api, components, pages, contexts, hooks, services—follow a feature‑based React organization.

##### README for Additional Insights
- Though minimal, the project name “CivicVoice” signals a civic‑tech use case.

##### Essential Elements to Capture
- Authentication flow, including login, JWT issuance, and middleware enforcement.
- Media upload path: client ➔ uploadController ➔ Cloudinary ➔ Database reference.
- Complaint lifecycle: createComplaint ➔ stored via Prisma ➔ fetched via complaintController.
- Role differentiation: which controllers/routes each role can access.
- Data storage: database schema (users, complaints, upvotes, media).
- Deployment target: Vercel entrypoints.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interaction
    Users["Users\n(Citizens, Authorities, Admins)"]:::external
    Users -->|"Interacts via Browser/Mobile"| FrontendEntry

    %% Frontend Layer
    subgraph "Frontend (React SPA)"
        direction TB
        FrontendEntry["React Entry Point\n(index.tsx)"]:::frontend
        App["Main App Component\n(App.tsx)"]:::frontend
        Routing["Frontend Routing & Pages\n(pages/)"]:::frontend
        Components["UI Components\n(components/)"]:::frontend
        Axios["Axios HTTP Client\n(axiosInstance.ts)"]:::frontend
        AuthContext["Authentication Context\n(auth-context.tsx)"]:::frontend
        UseAuth["Custom Auth Hook\n(useAuth.ts)"]:::frontend
        AuthServices["Frontend Auth Services\n(authServices.ts)"]:::frontend
        ProtectedRoutes["Protected Routes Wrapper\n(protectedRoutes.tsx)"]:::frontend

        FrontendEntry --> App
        App --> Routing
        App --> Components
        App --> AuthContext
        AuthContext --> UseAuth
        AuthServices --> Axios
        App -->|Uses| Axios
        App -->|Wraps| ProtectedRoutes
        ProtectedRoutes -->|Guards| Routing
    end

    FrontendEntry -->|"HTTP(S) Calls via Axios"| BackendApp

    %% Backend Layer
    subgraph "Backend (Node.js/Express API)"
        direction TB
        BackendApp["Express App\n(app.ts)"]:::backend
        Routes["Express Routes\n(routes/)"]:::backend
        Controllers["Express Controllers\n(controllers/)"]:::backend
        Services["Business Logic Services\n(services/)"]:::backend
        Middlewares["Middleware Layer\n(middlewares/)"]:::backend
        PrismaClient["Prisma Client Utility\n(prismaClient.ts)"]:::backend
        JwtUtils["Authentication Utilities\n(jwtUtils.ts)"]:::backend
        HashPassword["Password Hashing Utility\n(hashPassword.ts)"]:::backend
        ComplaintHelper["Complaint Helper Utilities\n(complaintHelper.ts)"]:::backend
        CloudinaryConfig["Cloudinary Configuration\n(cloudinary.ts)"]:::backend
        UploadUtil["File Upload Utility\n(uploadToCloudinary.ts)"]:::backend
        TranscribeHelper["Transcription Helper\n(transcribeHelper.ts)"]:::backend

        BackendApp --> Routes
        Routes --> Controllers
        Controllers --> Services
        Services --> PrismaClient
        Controllers -->|Calls| UploadUtil
        UploadUtil --> CloudinaryExternal
        Controllers -->|Calls| TranscribeHelper
        Controllers --> JwtUtils
        Controllers --> HashPassword
        Middlewares --> JwtUtils
        Middlewares -->|Role Checks| Controllers
        Services --> ComplaintHelper
        Services --> AuthService

        subgraph AuthServiceModule["Auth Service"]
            AuthService["Auth Logic Service\n(authService.ts)"]:::backend
        end
        Services --> AuthService
    end

    %% Database and External Services
    subgraph "Data & External Services"
        direction TB
        Database["Relational Database\n(Prisma Schema)"]:::database
        CloudinaryExternal["Cloudinary Media Storage"]:::external
        TranscriptionAPI["Transcription API\n(speech-to-text)"]:::external
        Database -->|Stores Data| Controllers
    end

    BackendApp --> Database

    %% Deployment
    subgraph "Deployment (Vercel)"
        FEDeploy["Frontend vercel.json"]:::external
        BEDeploy["Backend vercel.json"]:::external
    end
    FEDeploy -.-> FrontendEntry
    BEDeploy -.-> BackendApp

    %% Click Events
    click FrontendEntry "https://github.com/hirtikmalvi/civicvoice/blob/main/frontend/src/index.tsx"
    click App "https://github.com/hirtikmalvi/civicvoice/blob/main/frontend/src/App.tsx"
    click Routing "https://github.com/hirtikmalvi/civicvoice/tree/main/frontend/src/pages"
    click Components "https://github.com/hirtikmalvi/civicvoice/tree/main/frontend/src/components"
    click Axios "https://github.com/hirtikmalvi/civicvoice/blob/main/frontend/src/api/axiosInstance.ts"
    click AuthContext "https://github.com/hirtikmalvi/civicvoice/blob/main/frontend/src/contexts/auth-context.tsx"
    click UseAuth "https://github.com/hirtikmalvi/civicvoice/blob/main/frontend/src/hooks/useAuth.ts"
    click AuthServices "https://github.com/hirtikmalvi/civicvoice/blob/main/frontend/src/services/authServices.ts"
    click ProtectedRoutes "https://github.com/hirtikmalvi/civicvoice/blob/main/frontend/src/components/protectedRoutes.tsx"
    click BackendApp "https://github.com/hirtikmalvi/civicvoice/blob/main/backend/app.ts"
    click Controllers "https://github.com/hirtikmalvi/civicvoice/tree/main/backend/controllers"
    click Routes "https://github.com/hirtikmalvi/civicvoice/tree/main/backend/routes"
    click AuthService "https://github.com/hirtikmalvi/civicvoice/blob/main/backend/services/authService.ts"
    click Middlewares "https://github.com/hirtikmalvi/civicvoice/tree/main/backend/middlewares"
    click Database "https://github.com/hirtikmalvi/civicvoice/blob/main/backend/prisma/schema.prisma"
    click PrismaClient "https://github.com/hirtikmalvi/civicvoice/blob/main/backend/utils/prismaClient.ts"
    click JwtUtils "https://github.com/hirtikmalvi/civicvoice/blob/main/backend/utils/jwtUtils.ts"
    click HashPassword "https://github.com/hirtikmalvi/civicvoice/blob/main/backend/utils/hashPassword.ts"
    click ComplaintHelper "https://github.com/hirtikmalvi/civicvoice/blob/main/backend/utils/complaintHelpter.ts"
    click CloudinaryConfig "https://github.com/hirtikmalvi/civicvoice/blob/main/backend/config/cloudinary.ts"
    click UploadUtil "https://github.com/hirtikmalvi/civicvoice/blob/main/backend/utils/uploadToCloudinary.ts"
    click TranscribeHelper "https://github.com/hirtikmalvi/civicvoice/blob/main/backend/utils/transcribeHelper.ts"
    click FEDeploy "https://github.com/hirtikmalvi/civicvoice/blob/main/frontend/vercel.json"
    click BEDeploy "https://github.com/hirtikmalvi/civicvoice/blob/main/backend/vercel.json"

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#004085,color:#004085;
    classDef backend fill:#d4edda,stroke:#155724,color:#155724;
    classDef database fill:#f8d7da,stroke:#721c24,color:#721c24,shape:cylinder;
    classDef external fill:#fff3cd,stroke:#856404,color:#856404;
```
