# hack-psu/api architecture

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

- Interactive diagram: https://gitdiagram.com/hack-psu/api
- Repository: https://github.com/hack-psu/api

## Overview

##### Project type and purpose
- This is a backend monolith (RESTful API) for HackPSU’s hackathon platform (v2).
- It is built in Node.js (TypeScript), runs on Google App Engine, and exposes /v2 REST endpoints for users, admins, scanners, live updates, judging, etc.
- It uses Google Cloud SQL (MySQL), Firebase Realtime Database, and various external services (email, push notifications, storage, auth).

##### File structure
Top-level:
- app.ts / bin/www – application bootstrap & Express server startup.
- src/JSCommon – shared types, error definitions, utilities.
- src/assets – SQL scripts, JSON schemas, email templates, constants.
- src/models – Model classes + DataMapper implementations (CRUD & queries) organized by domain (RSVP, event, location, attendance…).
- src/processors – Business-logic facades that orchestrate DataMappers.
- src/router – Express routes & controllers (one per API group).
- src/services – External integrations & infrastructure:
– auth (Firebase, API-key, RBAC)
– database (connection factories for SQL & RTDB, Unit-of-Work, generic data mappers, cache layer: Redis/Memcache)
– communication (email via SendGrid/Mailchimp, push via OneSignal, websocket pusher)
– storage (GCS engine & mappers)
– logging/monitoring, rate limiter, DI injector.
- src/views – Pug templates (error/index).
- db/ – raw SQL, schema scripts.
- config files – app.yaml, dispatch.yaml, Gruntfile (decrypt sensitive), Travis CI config, TypeScript config.

##### Key architectural insights from README
- Layered architecture: RouteControllers → Processors → DataMappers → Database.
- Services for all external integrations (isolated, mockable).
- Dependency Injection (injection-js) wires everything.
- AJV validators enforce JSON schemas on incoming payloads.
- CI/CD via Travis → deploys to App Engine; tests with Mocha/Chai and E2E suite.

1. Client (Mobile/Web)
2. Load Balancer / App Engine Front End
3. Express API Server (Node.js)
- Router / RouteControllers
- Processors (Business Logic)
- DataMappers (Repository Layer)
- Models & AJV Schema Validators
- DI Container
4. Services:
– Auth Service (Firebase Auth, API-Key, RBAC)
– Database Service:
- Cloud SQL (MySQL) via proxy
- Firebase Realtime DB
- Cache (Redis or Memcache)
– Communication Services:
- Email (SendGrid, Mailchimp)
- Push Notifications (OneSignal)
- WebSocket Pusher
– Storage Service (Google Cloud Storage)
– Logging / Monitoring
5. Admin Clients (third-party UIs)
6. CI/CD Pipeline (Travis CI → App Engine)

- Client → HTTP(S) → Load Balancer → Express Router
- Router → Controller → Processor → DataMapper → Database/Cache
- Controllers & Processors pull in Services via DI
- Database writes/reads via Unit-of-Work & Connection Factories
- External calls: Auth checks to Firebase Auth, writes to RTDB, emails via SendGrid, push via OneSignal, storage reads/writes to GCS
- Logging calls from Controllers/Services to Cloud Logging

C. Architectural patterns & design principles:
- Layered / Onion architecture (controllers, services, data)
- Repository pattern (DataMapper)
- Dependency Injection for decoupling & testability
- Single Responsibility: each service has one concern
- Schema validation at boundary (AJV)

D. Key technologies / libraries:
– Node.js & Express.js, TypeScript
– injection-js (DI framework)
– AJV (JSON Schema validation)
– Google Cloud SQL Proxy, MySQL
– Firebase Auth & RTDB
– Redis / Memcache
– SendGrid / Mailchimp, OneSignal
– Google Cloud Storage
– Mocha, Chai (testing)
– Travis CI, App Engine

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Clients
    subgraph "Clients"
        A_Client["Mobile/Web Client"]:::external
        A_Admin["Admin Client"]:::external
    end

    %% Infrastructure
    subgraph "Infrastructure" 
        LB["Load Balancer / App Engine"]:::infra
        DI["Dependency Injection Container"]:::infra
    end

    %% Express API Server
    subgraph "Express API Server (Node.js)" 
        direction TB
        subgraph "HTTP Layer" 
            RC["Router / RouteControllers"]:::controller
        end
        subgraph "Business Logic Layer"
            P1["IndexProcessor"]:::processor
            P2["AdminProcessor"]:::processor
            P3["PreRegistrationProcessor"]:::processor
            P4["RegistrationProcessor"]:::processor
            P5["ScannerProcessor"]:::processor
            P6["UpdateProcessor"]:::processor
        end
        subgraph "Data Access Layer"
            DM1["RSVPDataMapper"]:::datamapper
            DM2["EventDataMapper"]:::datamapper
            DM3["AdminDataMapper"]:::datamapper
            DM4["AttendanceDataMapper"]:::datamapper
        end
        subgraph "Models & Validation"
            M["Domain Models"]:::model
            V["AJV Schema Validators"]:::validator
        end
        click RC "https://github.com/hack-psu/api/blob/dev/src/router/index.ts"
        click P1 "https://github.com/hack-psu/api/blob/dev/src/processors/index-processor.ts"
        click P2 "https://github.com/hack-psu/api/blob/dev/src/processors/admin-processor.ts"
        click P3 "https://github.com/hack-psu/api/blob/dev/src/processors/pre-registration-processor.ts"
        click P4 "https://github.com/hack-psu/api/blob/dev/src/processors/registration-processor.ts"
        click P5 "https://github.com/hack-psu/api/blob/dev/src/processors/scanner-processor.ts"
        click P6 "https://github.com/hack-psu/api/blob/dev/src/processors/update-processor.ts"
        click DM1 "https://github.com/hack-psu/api/blob/dev/src/models/RSVP/RSVP-data-mapper-impl.ts"
        click DM2 "https://github.com/hack-psu/api/blob/dev/src/models/event/event-data-mapper-impl.ts"
        click DM3 "https://github.com/hack-psu/api/blob/dev/src/models/admin/admin-data-mapper-impl.ts"
        click DM4 "https://github.com/hack-psu/api/blob/dev/src/models/attendance/attendance-data-mapper-impl.ts"
        click M "https://github.com/hack-psu/api/blob/dev/src/models/rsvp.ts"
        click V "https://github.com/hack-psu/api/blob/dev/src/assets/schemas/json-asset-loader.ts"
    end

    %% Services
    subgraph "Services" 
        direction TB
        subgraph "Auth Service" 
            Auth1["FirebaseAuth"]:::service
            Auth2["APIKeyAuth"]:::service
            Auth3["RBAC"]:::service
        end
        subgraph "Database Service"
            DB1["Cloud SQL (MySQL)"]:::service
            DB2["Firebase RTDB"]:::service
            Cache["Redis/Memcache"]:::service
        end
        subgraph "Communication"
            Email["Email Service"]:::service
            Push["Push Notification"]:::service
            WS["WebSocket Pusher"]:::service
        end
        subgraph "Storage Service"
            Storage["Google Cloud Storage"]:::service
        end
        subgraph "Logging & Monitoring"
            Log["Logging"]:::service
            Mon["Monitoring"]:::service
        end
        subgraph "Rate Limiter"
            RL["Rate Limiter"]:::service
        end
        click Auth1 "https://github.com/hack-psu/api/blob/dev/src/services/auth/firebase-auth.ts"
        click Auth2 "https://github.com/hack-psu/api/blob/dev/src/services/auth/apikey-auth.ts"
        click Auth3 "https://github.com/hack-psu/api/blob/dev/src/services/auth/RBAC/rbac.ts"
        click DB1 "https://github.com/hack-psu/api/blob/dev/src/services/database/connection/sql-connection-factory.ts"
        click DB2 "https://github.com/hack-psu/api/blob/dev/src/services/database/connection/rtdb-connection-factory.ts"
        click Cache "https://github.com/hack-psu/api/blob/dev/src/services/database/cache/redis-impl.service.ts"
        click Email "https://github.com/hack-psu/api/blob/dev/src/services/communication/email/email.service.ts"
        click Push "https://github.com/hack-psu/api/blob/dev/src/services/communication/push-notification/push-notif.service.ts"
        click WS "https://github.com/hack-psu/api/blob/dev/src/services/communication/websocket-pusher.ts"
        click Storage "https://github.com/hack-psu/api/blob/dev/src/services/storage/svc/google-storage.service.ts"
        click Log "https://github.com/hack-psu/api/blob/dev/src/services/logging/logging.ts"
        click Mon "https://github.com/hack-psu/api/blob/dev/src/services/logging/monitoring.ts"
        click RL "https://github.com/hack-psu/api/blob/dev/src/services/common/rate-limiter/rate-limiter.service.ts"
    end

    %% Databases & External
    subgraph "External Data Stores"
        SQL["Cloud SQL (MySQL)"]:::db
        RTDB["Firebase Realtime DB"]:::db
        REDIS["Redis / Memcache"]:::db
    end

    %% CI/CD
    subgraph "CI/CD Pipeline"
        CI["Travis CI → App Engine"]:::infra
    end

    %% Application Bootstrap
    subgraph "Bootstrap"
        App["app.ts / bin/www"]:::infra
        click App "https://github.com/hack-psu/api/blob/dev/src/app.ts"
        click App "https://github.com/hack-psu/api/tree/dev/src/bin/www"
    end

    %% Assets & Scripts
    subgraph "Assets & Config"
        Schemas["JSON Schemas"]:::asset
        Utils["Shared Utilities"]:::asset
        click Schemas "https://github.com/hack-psu/api/blob/dev/src/assets/schemas/*.json"
        click Utils "https://github.com/hack-psu/api/blob/dev/src/JSCommon/common-types.ts"
        Config["Config & CI files"]:::asset
        click Config "https://github.com/hack-psu/api/blob/dev/app.yaml"
        click Config "https://github.com/hack-psu/api/blob/dev/ .travis.yml"
    end

    %% Connections
    A_Client -->|"HTTPS"| LB --> App --> RC
    A_Admin -->|"HTTPS"| LB
    RC -->|"calls"| P1
    RC -->|"calls"| P2
    RC -->|"calls"| P3
    P1 -->|"uses"| DM1
    P2 -->|"uses"| DM3
    P3 -->|"uses"| DM1
    P4 -->|"uses"| DM2
    P5 -->|"uses"| DM4
    P6 -->|"uses"| DM2
    P1 -->|"loads models"| M
    P1 -->|"validates via"| V
    RC -->|"injects via"| DI
    P1 -->|"injects via"| DI
    DM1 -->|"injects via"| DI
    DM2 -->|"injects via"| DI
    DI --> Auth1
    DI --> Auth2
    DI --> Auth3
    DI --> DB1
    DI --> DB2
    DI --> Cache
    DI --> Email
    DI --> Push
    DI --> WS
    DI --> Storage
    DI --> Log
    DI --> Mon
    DI --> RL
    DM1 -->|"reads/writes"| SQL
    DM2 -->|"reads/writes"| SQL
    DM3 -->|"reads/writes"| SQL
    DM4 -->|"reads/writes"| SQL
    DM1 -->|"reads/writes"| RTDB
    DM2 -->|"reads/writes"| RTDB
    DM1 -->|"caches"| REDIS
    RC -->|"logs to"| Log
    Email -->|"sends via"| External_Email["SendGrid/Mailchimp"]:::external
    Push -->|"sends via"| External_Push["OneSignal"]:::external
    WS -->|"pushes updates"| RTDB
    CI --> LB

    %% Legend
    subgraph "Legend"
        C1["Internal Controllers/Processors/DataMappers"]:::blue
        C2["External Services/Databases"]:::green
        C3["Infrastructure"]:::orange
    end

    classDef controller fill:#D0E6FF,stroke:#0257C5;
    classDef processor fill:#D0E6FF,stroke:#0257C5;
    classDef datamapper fill:#D0E6FF,stroke:#0257C5;
    classDef model fill:#D0E6FF,stroke:#0257C5;
    classDef validator fill:#D0E6FF,stroke:#0257C5;
    classDef service fill:#D4F8D4,stroke:#2F8F2F;
    classDef db fill:#D4F8D4,stroke:#2F8F2F;
    classDef external fill:#FBE4D4,stroke:#C96A00;
    classDef infra fill:#FFE4B3,stroke:#FF8C00;
    classDef asset fill:#F0E6FF,stroke:#8000FF;
    class C1 controller,processor,datamapper,model,validator;
    class C2 service,db,external;
    class C3 infra,asset;
```
