# slowdust18/civic_guardian architecture

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

- Interactive diagram: https://gitdiagram.com/slowdust18/civic_guardian
- Repository: https://github.com/slowdust18/civic_guardian

## Overview

##### Main Components (arranged left→right)
- Frontend (React SPA)
– Components: LoginPage, ComplaintPage, MapPage, AdminPage
– Bundler: npm/webpack
– Fetch layer: src/api.js
- Backend (FastAPI)
– Entry point: main.py
– Routers: admin, user, complaints, votes, autofillAi, resolved
– Business logic: crud.py, seed.py
– Models & schemas: models.py, schemas.py
– Migrations: Alembic (versions folder)
- Database & Storage
– PostgreSQL + PostGIS (database.py)
– Migration state: alembic.ini + env.py
– File store: /uploads (complaint images)
- External Services (optional)
– Map provider (e.g., Google Maps)
– AI autofill service (router: autofillAi)

##### Relationships & Data Flows
- Frontend → Backend
– HTTP(S) requests to endpoints (e.g., GET /complaints/all, POST /votes).
- Backend → Database
– SQLAlchemy ORM calls to PostgreSQL
– Alembic migrations update schema
- Backend → Storage
– File upload/download to local /uploads
- (Optional) Backend → External AI/Map service

##### Architectural Patterns
- Layered architecture (Presentation → API → Data)
- Router-based modularity (one router per feature)
- ORM + Migration toolchain (SQLAlchemy + Alembic)
- Separation of concerns:
– CRUD layer (crud.py)
– Schema validation (Pydantic schemas.py)

##### Technologies & Frameworks
- React (JSX, CSS modules)
- FastAPI (Starlette, Pydantic)
- PostgreSQL + PostGIS
- SQLAlchemy + Alembic
- Node.js / npm

## Diagram (Mermaid)

```mermaid
flowchart LR
    %% Frontend Layer
    subgraph "Frontend (React SPA)"
        direction TB
        LoginPage["LoginPage"]:::frontend
        ComplaintPage["ComplaintPage"]:::frontend
        MapPage["MapPage"]:::frontend
        AdminPage["AdminPage"]:::frontend
        APIClient["api.js"]:::frontend
        Bundler["package.json"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend (FastAPI)" 
        direction TB
        Main["main.py"]:::backend
        subgraph "Routers"
            direction TB
            AdminRouter["admin.py"]:::backend
            UserRouter["user.py"]:::backend
            ComplaintsRouter["complaints.py"]:::backend
            VotesRouter["votes.py"]:::backend
            AutofillRouter["autofillAi.py"]:::backend
            ResolvedRouter["resolved.py"]:::backend
        end
        CRUD["crud.py"]:::backend
        Seed["seed.py"]:::backend
        Models["models.py"]:::backend
        Schemas["schemas.py"]:::backend
        DBConn["database.py"]:::backend
        subgraph "Alembic"
            direction TB
            AConfig["alembic.ini"]:::backend
            AEnv["env.py"]:::backend
            AVersions["versions/"]:::backend
        end
        StaticTemplate["static/complaints.html"]:::backend
        Uploads["uploads/"]:::storage
    end

    %% Database
    Postgres[(PostgreSQL + PostGIS)]:::db

    %% External Services
    subgraph "External Services"
        direction TB
        MapService["Map Provider"]:::external
        AIService["AI Autofill Service"]:::external
    end

    %% Connections
    LoginPage --> APIClient
    ComplaintPage --> APIClient
    MapPage --> APIClient
    AdminPage --> APIClient
    Bundler --> APIClient
    APIClient -->|"HTTP"| Main
    Main --> AdminRouter
    Main --> UserRouter
    Main --> ComplaintsRouter
    Main --> VotesRouter
    Main --> AutofillRouter
    Main --> ResolvedRouter
    AdminRouter --> CRUD
    UserRouter --> CRUD
    ComplaintsRouter --> CRUD
    VotesRouter --> CRUD
    AutofillRouter --> CRUD
    ResolvedRouter --> CRUD
    CRUD --> Models
    CRUD --> Schemas
    CRUD --> DBConn
    DBConn --> Postgres
    AConfig -.-> Postgres
    AEnv -.-> Postgres
    AVersions -.-> Postgres
    Main --> Uploads
    Main -->|"HTTP"| MapService
    AutofillRouter -->|"HTTP"| AIService

    %% Click events
    click LoginPage "https://github.com/slowdust18/civic_guardian/blob/main/frontend/src/components/LoginPage.js"
    click ComplaintPage "https://github.com/slowdust18/civic_guardian/blob/main/frontend/src/components/ComplaintPage.js"
    click MapPage "https://github.com/slowdust18/civic_guardian/blob/main/frontend/src/components/MapPage.js"
    click AdminPage "https://github.com/slowdust18/civic_guardian/blob/main/frontend/src/components/AdminPage.jsx"
    click APIClient "https://github.com/slowdust18/civic_guardian/blob/main/frontend/src/api.js"
    click Bundler "https://github.com/slowdust18/civic_guardian/blob/main/frontend/package.json"
    click Main "https://github.com/slowdust18/civic_guardian/blob/main/backend/main.py"
    click AdminRouter "https://github.com/slowdust18/civic_guardian/blob/main/backend/routers/admin.py"
    click UserRouter "https://github.com/slowdust18/civic_guardian/blob/main/backend/routers/user.py"
    click ComplaintsRouter "https://github.com/slowdust18/civic_guardian/blob/main/backend/routers/complaints.py"
    click VotesRouter "https://github.com/slowdust18/civic_guardian/blob/main/backend/routers/votes.py"
    click AutofillRouter "https://github.com/slowdust18/civic_guardian/blob/main/backend/routers/autofillAi.py"
    click ResolvedRouter "https://github.com/slowdust18/civic_guardian/blob/main/backend/routers/resolved.py"
    click CRUD "https://github.com/slowdust18/civic_guardian/blob/main/backend/crud.py"
    click Seed "https://github.com/slowdust18/civic_guardian/blob/main/backend/seed.py"
    click Models "https://github.com/slowdust18/civic_guardian/blob/main/backend/models.py"
    click Schemas "https://github.com/slowdust18/civic_guardian/blob/main/backend/schemas.py"
    click DBConn "https://github.com/slowdust18/civic_guardian/blob/main/backend/database.py"
    click AConfig "https://github.com/slowdust18/civic_guardian/blob/main/backend/alembic.ini"
    click AEnv "https://github.com/slowdust18/civic_guardian/blob/main/backend/alembic/env.py"
    click AVersions "https://github.com/slowdust18/civic_guardian/tree/main/backend/alembic/versions/"
    click Uploads "https://github.com/slowdust18/civic_guardian/tree/main/backend/uploads/"

    %% Styles
    classDef frontend fill:#dae8fc,stroke:#6c8ebf;
    classDef backend fill:#d5e8d4,stroke:#82b366;
    classDef db fill:#ffe6cc,stroke:#d79b00;
    classDef storage fill:#ffe6cc,stroke:#d79b00,stroke-dasharray: 5 5;
    classDef external fill:#f2f2f2,stroke:#999999,stroke-dasharray: 3 3;
```
