# tobiasmarion/pollo-backend architecture

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

- Interactive diagram: https://gitdiagram.com/tobiasmarion/pollo-backend
- Repository: https://github.com/tobiasmarion/pollo-backend

## Overview

##### Project type and purpose
- This is a backend-only, full-stack “API + real-time engine” project (no frontend code here).
- Purpose: let an authenticated admin create/close “events”, map participant phones to a 2D grid, then dispatch real-time “effect” commands via WebSockets. Participants listen and render local animations.

##### File structure
- Top-level config: .env, tsconfig.json, Docker Compose, ESLint, Prisma migrations.
- prisma/: holds schema.prisma, migration SQL files, raw SQL.
- src/server.ts: application entrypoint, spins up Fastify + WebSocket hooks.
- src/http/: HTTP controllers, error handlers, routes, middlewares (auth).
- src/http/routes/auth: GitHub OAuth authenticate, get user profile.
- src/http/routes/event: create-event, close-event, join/get-event/data.
- src/http/routes/websocket: upgrade endpoints for admin-event & join-event.
- src/services/event: business logic for event lifecycle, mapping users to grid, status.
- src/lib/prisma.ts: Prisma client. src/lib/env.ts: env var loader. src/lib/events.ts: possibly event emitter.
- src/utils: shared helper code.
- src/tests: simple scripts for seeding or local testing.

##### README for additional insights
- Admin issues HTTP calls to create/close, participants join even when closed.
- On close, server computes fixed grid (rows×columns based on user count+geo).
- Real-time “effect” commands flow from admin → server → broadcast over WebSocket → participants.
- No fixed frame rate; updates push only on state change.

##### Main components and interactions
a. Clients:
- Admin client (could be any HTTP+WS client)
- Participant clients (HTTP join + persistent WS)
b. API & real-time server (Fastify):
- HTTP layer (routes & middlewares)
- WebSocket layer (upgrade endpoints)
- Business services (event service, user-to-grid mapping)
- Prisma ORM layer interacting with PostgreSQL
c. Database (PostgreSQL via Prisma)
d. External service: GitHub OAuth for authentication
e. Infrastructure: Docker Compose orchestrating Node app + DB

##### Relationships & Data flows
1. Admin → (HTTPS) → Fastify HTTP/auth route → GitHub OAuth → obtains token/profile
2. Admin → (HTTPS) → Fastify HTTP/event route → Prisma writes events table
3. Participant → (HTTPS) → Fastify HTTP/event/join → Prisma writes participant record
4. Once event closed: Fastify triggers grid-generation service → updates DB
5. Admin → (WS) → Fastify WS/admin-event → Server broadcasts effect messages → subscribed WS participants
6. Participant WS clients receive JSON commands and update local state

##### Architectural patterns & design principles
- Layered architecture: HTTP controllers → Services → Repository/ORM → Database
- Clear separation of concerns: routing, error handling, business logic, data access
- Real-time pub/sub via WebSocket channel per event
- Database migrations via Prisma

- Labels for each route group (e.g., /auth, /event, /websocket)
- Middleware layer (Authentication) sitting between HTTP routes & service methods
- Docker Compose boundary showing containers: “api-service” and “postgres-db”

##### Detail without over-fragmenting
- Flows: REST, DB reads/writes, WebSocket broadcasts, OAuth handshake

## Diagram (Mermaid)

```mermaid
flowchart TB
    classDef client fill:#dddddd,stroke:#888888,color:#333333
    classDef app fill:#ffe5b4,stroke:#cc8400,color:#663300
    classDef db fill:#d0f0c0,stroke:#4caf50,color:#256029
    classDef external fill:#cfe2f3,stroke:#2a6cb0,color:#0b3669

    subgraph "Docker Compose"
        direction TB
        subgraph "api-service" 
            direction TB
            Entry["Application Entry Point"]:::app
            click Entry "https://github.com/tobiasmarion/pollo-backend/blob/main/src/server.ts"

            subgraph "HTTP Layer" 
                direction TB
                RoutesIndex["Route Definitions"]:::app
                click RoutesIndex "https://github.com/tobiasmarion/pollo-backend/blob/main/src/http/routes/index.ts"
                ErrorHandler["Error Handler"]:::app
                click ErrorHandler "https://github.com/tobiasmarion/pollo-backend/blob/main/src/http/error-handler.ts"
                AuthMiddleware["Authentication Middleware"]:::app
                click AuthMiddleware "https://github.com/tobiasmarion/pollo-backend/blob/main/src/http/middlewares/auth.ts"
            end

            subgraph "Auth Routes (/auth)" 
                direction TB
                AuthenticateGitHub["Authenticate with GitHub"]:::app
                click AuthenticateGitHub "https://github.com/tobiasmarion/pollo-backend/blob/main/src/http/routes/auth/authenticate-with-github.ts"
                GetProfile["Get User Profile"]:::app
                click GetProfile "https://github.com/tobiasmarion/pollo-backend/blob/main/src/http/routes/auth/get-profile.ts"
            end

            subgraph "Event Routes (/event)" 
                direction TB
                CreateEvent["Create Event"]:::app
                click CreateEvent "https://github.com/tobiasmarion/pollo-backend/blob/main/src/http/routes/event/create-event.ts"
                CloseEvent["Close Event"]:::app
                click CloseEvent "https://github.com/tobiasmarion/pollo-backend/blob/main/src/http/routes/event/close-event.ts"
                GetEvent["Get Event by ID"]:::app
                click GetEvent "https://github.com/tobiasmarion/pollo-backend/blob/main/src/http/routes/event/get-event.ts"
                GetEventByLocation["Get Event by Location"]:::app
                click GetEventByLocation "https://github.com/tobiasmarion/pollo-backend/blob/main/src/http/routes/event/get-event-by-location.ts"
                GetParticipants["Get Participants"]:::app
                click GetParticipants "https://github.com/tobiasmarion/pollo-backend/blob/main/src/http/routes/event/get-participants.ts"
            end

            subgraph "WebSocket Routes" 
                direction TB
                AdminEventWS["Admin Event WS Upgrade"]:::app
                click AdminEventWS "https://github.com/tobiasmarion/pollo-backend/blob/main/src/http/routes/websocket/admin-event.ts"
                JoinEventWS["Join Event WS Upgrade"]:::app
                click JoinEventWS "https://github.com/tobiasmarion/pollo-backend/blob/main/src/http/routes/websocket/join-event.ts"
            end

            subgraph "Service Layer" 
                direction TB
                EventService["Event Service"]:::app
                click EventService "https://github.com/tobiasmarion/pollo-backend/blob/main/src/services/event/index.ts"
                EventTypes["Event Types"]:::app
                click EventTypes "https://github.com/tobiasmarion/pollo-backend/blob/main/src/services/event/types.d.ts"
            end

            subgraph "ORM & Config" 
                direction TB
                PrismaClient["Prisma Client"]:::app
                click PrismaClient "https://github.com/tobiasmarion/pollo-backend/blob/main/src/lib/prisma.ts"
                EnvLoader["Env Loader"]:::app
                click EnvLoader "https://github.com/tobiasmarion/pollo-backend/blob/main/src/lib/env.ts"
                EventsUtil["Event Emitter Utility"]:::app
                click EventsUtil "https://github.com/tobiasmarion/pollo-backend/blob/main/src/lib/events.ts"
                Utils["Shared Utilities"]:::app
                click Utils "https://github.com/tobiasmarion/pollo-backend/blob/main/src/utils/index.ts"
            end
        end

        subgraph "postgres-db" 
            direction TB
            Database["PostgreSQL"]:::db
            click Database "https://github.com/tobiasmarion/pollo-backend/blob/main/prisma/schema.prisma"
            Migrations["Migrations & SQL"]:::db
            click Migrations "https://github.com/tobiasmarion/pollo-backend/blob/main/prisma/migrations/*.sql"
            click Migrations "https://github.com/tobiasmarion/pollo-backend/blob/main/prisma/sql/getClosestEvent.sql"
        end
    end

    subgraph "Clients"
        direction TB
        AdminClient["Admin Client"]:::client
        ParticipantClient["Participant Client"]:::client
    end

    GitHubOAuth["GitHub OAuth"]:::external

    %% Connections
    AdminClient -->|REST /auth| AuthenticateGitHub
    AuthenticateGitHub -->|callback| Entry
    AdminClient -->|REST /event| CreateEvent
    CreateEvent -->|service call| EventService
    CloseEvent -->|service call| EventService
    ParticipantClient -->|REST /event/join| GetEvent
    GetEvent -->|service call| EventService

    Entry --> RoutesIndex
    RoutesIndex --> AuthMiddleware
    AuthMiddleware --> AuthRoutes
    AuthMiddleware --> EventRoutes

    EventService --> PrismaClient
    PrismaClient --> Database
    EventService --> EventsUtil

    AdminClient -->|WS connect| AdminEventWS
    ParticipantClient -->|WS connect| JoinEventWS
    AdminEventWS -->|broadcast| JoinEventWS

    GitHubOAuth -->|token| Entry

    class AdminClient,ParticipantClient client
    class Entry,RoutesIndex,ErrorHandler,AuthMiddleware,AuthenticateGitHub,GetProfile,CreateEvent,CloseEvent,GetEvent,GetEventByLocation,GetParticipants,AdminEventWS,JoinEventWS,EventService,EventTypes,PrismaClient,EnvLoader,EventsUtil,Utils app
    class Database,Migrations db
    class GitHubOAuth external
```
