How tobiasmarion/pollo-backend works
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