How hack-psu/api works
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