# whooses/unimap architecture

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

- Interactive diagram: https://gitdiagram.com/whooses/unimap
- Repository: https://github.com/whooses/unimap

## Overview

##### Project type and purpose
- This is a full-stack mobile application named “Unimap” for sharing university event information.
- client/ holds an iOS SwiftUI app (MVVM)
- server/ holds a Python FastAPI service (routers → services → repository → DB)
- supabase/ holds database schema migrations + seed scripts (PostgreSQL)
- CI/CD is defined in .github/workflows/CICD.yml and the server is containerized via Dockerfile

a. Mobile client (SwiftUI app)
- Layers:
– UI (Pages, Components)
– ViewModels (AuthViewModel, ExplorePageVM, etc.)
– Services (NetworkService, EventService, etc.)
– Utilities (URLRequestBuilder, ImageLoader)
- External dependency: Auth0 (client/Unimap/Configs/Auth0.plist)
b. API server (FastAPI)
- Routers (users, events, bug_reports, event_reports)
- Dependencies (auth_dep, database_dep, etc.)
- Services (event_service, user_service, report services)
- Repository / DB layer (SQLAlchemy models + repository classes)
c. Database (PostgreSQL via Supabase)
- Schema managed by supabase/migrations
d. Authentication service (Auth0, issuing JWT tokens)
e. CI/CD pipeline (GitHub Actions)
f. Containerization (Dockerfile for server)

##### Relationships & data flows
- Mobile App → Auth0: OAuth/OpenID login → receives JWT
- Mobile App → FastAPI: HTTPS/JSON requests carrying JWT in header
- FastAPI → PostgreSQL (Supabase): query/ transaction via SQLAlchemy session
- FastAPI → Auth0 (token validation via dependencies/auth_dep)
- CI/CD Workflow → builds & pushes Docker image → deploys server → runs database migrations (supabase)

##### Architectural patterns & principles
- Client: MVVM (Views ↔ ViewModels ↔ Services)
- Server: Layered architecture (Routers → Business Services → Repository → Models)
- Use of dependency injection for database and auth deps in FastAPI
- Infrastructure as code for DB schema (supabase migrations)
- Container-first deployment via Docker

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Mobile Client Layer
    subgraph "Mobile Client (SwiftUI App)"
        direction TB
        UI["UI Layer"]:::client
        VM["ViewModels"]:::client
        SVC["Services"]:::client
        UTIL["Utilities"]:::client
        CONFIG["Auth0 Config"]:::client
    end

    %% Auth Service
    AUTH0["Auth0 Service"]:::external

    %% Backend API Layer
    subgraph "Backend API (FastAPI)"
        direction TB
        MAIN["main.py"]:::server
        subgraph "Routers"
            direction TB
            USERS["users router"]:::server
            EVENTS["events router"]:::server
            BUGS["bug_reports router"]:::server
            EVENT_REP["event_reports router"]:::server
        end
        subgraph "Dependencies"
            direction TB
            AUTH_DEP["auth_dep"]:::server
            DB_DEP["database_dep"]:::server
            EVT_DEP["event_dep"]:::server
            BUG_DEP["bug_report_dep"]:::server
            EVTREP_DEP["event_report_dep"]:::server
        end
        subgraph "Services"
            direction TB
            EVT_SVC["event_service"]:::server
            BUG_SVC["bug_report_service"]:::server
            EVTREP_SVC["event_report_service"]:::server
        end
        subgraph "Repository / DB Layer"
            direction TB
            MODELS["SQLAlchemy models"]:::server
            REPO["Repository classes"]:::server
            SESSION["session setup"]:::server
        end
    end

    %% Database Layer
    subgraph "Database (PostgreSQL via Supabase)"
        direction TB
        MIGRATIONS["supabase/migrations"]:::db
        SEED["supabase/seed.sql"]:::db
    end

    %% CI/CD Pipeline
    subgraph "CI/CD Pipeline (GitHub Actions)"
        direction TB
        CI[".github/workflows/CICD.yml"]:::infra
        DOCKER["Dockerfile"]:::infra
        BUILD["Build & Push Image"]:::infra
        MIGRATE["Run Migrations"]:::infra
        DEPLOY["Deploy Server"]:::infra
    end

    %% Client MVVM Flow
    UI -->|"binds to"| VM
    VM -->|"calls"| SVC
    SVC -->|"OAuth2/OpenID"| AUTH0
    SVC -->|"HTTPS/JSON JWT"| MAIN

    %% API Flow
    MAIN -->|"/users, /events, /reports"| USERS
    MAIN -->|"depends on"| AUTH_DEP
    MAIN -->|"depends on"| DB_DEP
    USERS -->|"uses"| EVT_SVC
    EVENTS -->|"uses"| EVT_SVC
    BUGS -->|"uses"| BUG_SVC
    EVENT_REP -->|"uses"| EVTREP_SVC
    AUTH_DEP -->|"validates JWT with"| AUTH0
    DB_DEP -->|"opens session"| SESSION
    EVT_SVC -->|"queries"| REPO
    BUG_SVC -->|"queries"| REPO
    EVTREP_SVC -->|"queries"| REPO
    REPO -->|"uses models"| MODELS
    REPO -->|"executes SQL"| SESSION
    MAIN -->|"runs in container built from"| DOCKER

    %% Backend to Database
    SESSION -->|"SQL"| MIGRATIONS
    SESSION -->|"SQL"| SEED

    %% CI/CD Flow
    CI -->|runs tests &| BUILD
    BUILD -->|"pushes image"| DEPLOY
    DEPLOY -->|"applies"| MIGRATE
    DEPLOY -->|"starts service"| MAIN

    %% Styles
    classDef client fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef server fill:#90EE90,stroke:#000,stroke-width:1px
    classDef external fill:#FFA500,stroke:#000,stroke-width:1px
    classDef db fill:#FFD700,stroke:#000,stroke-width:1px
    classDef infra fill:#D3D3D3,stroke:#000,stroke-width:1px

    %% Click Events
    click UI "https://github.com/whooses/unimap/tree/main/client/Unimap/Pages"
    click SVC "https://github.com/whooses/unimap/tree/main/client/Unimap/Services"
    click VM "https://github.com/whooses/unimap/tree/main/client/Unimap/ViewModels"
    click UTIL "https://github.com/whooses/unimap/tree/main/client/Unimap/Utilities"
    click CONFIG "https://github.com/whooses/unimap/blob/main/client/Unimap/Configs/Auth0.plist"
    click MAIN "https://github.com/whooses/unimap/blob/main/server/main.py"
    click USERS "https://github.com/whooses/unimap/blob/main/server/routers/users.py"
    click EVENTS "https://github.com/whooses/unimap/blob/main/server/routers/events.py"
    click BUGS "https://github.com/whooses/unimap/blob/main/server/routers/bug_reports.py"
    click EVENT_REP "https://github.com/whooses/unimap/blob/main/server/routers/event_reports.py"
    click AUTH_DEP "https://github.com/whooses/unimap/blob/main/server/dependencies/auth_dep.py"
    click DB_DEP "https://github.com/whooses/unimap/blob/main/server/dependencies/database_dep.py"
    click EVT_DEP "https://github.com/whooses/unimap/blob/main/server/dependencies/event_dep.py"
    click BUG_DEP "https://github.com/whooses/unimap/blob/main/server/dependencies/bug_report_dep.py"
    click EVTREP_DEP "https://github.com/whooses/unimap/blob/main/server/dependencies/event_report_dep.py"
    click EVT_SVC "https://github.com/whooses/unimap/blob/main/server/services/event/event_service.py"
    click BUG_SVC "https://github.com/whooses/unimap/blob/main/server/services/reports/bug_report_service.py"
    click EVTREP_SVC "https://github.com/whooses/unimap/blob/main/server/services/reports/event_report_service.py"
    click MODELS "https://github.com/whooses/unimap/tree/main/server/db/models"
    click REPO "https://github.com/whooses/unimap/tree/main/server/db/repository"
    click SESSION "https://github.com/whooses/unimap/blob/main/server/db/session.py"
    click DOCKER "https://github.com/whooses/unimap/tree/main/server/Dockerfile"
    click CI "https://github.com/whooses/unimap/blob/main/.github/workflows/CICD.yml"
    click MIGRATIONS "https://github.com/whooses/unimap/tree/main/supabase/migrations"
    click SEED "https://github.com/whooses/unimap/blob/main/supabase/seed.sql"
```
