How staroverlay/backend works
Project type and purpose
• This is the “StarOverlay Backend,” a modular monolithic GraphQL API server written in NestJS. It powers the StarOverlay full‑stack application by exposing GraphQL queries, mutations and subscriptions, handling authentication, persisting data in MongoDB, orchestrating real‑time events via Socket.IO, and integrating with external services (Twitch API, email, payments, file storage).
File structure
• Top‑level:
• config, lint, Docker, CI files (.env.sample, Dockerfile, docker-compose.yml, railway.toml, jest.config.json)
• src: main entry (main.ts), app module/controller, global decorators, pipes, utils
• src/modules: one folder per feature (auth, users, sessions, profiles, plan, payments, media, templates, acquisition, integration, membership, widgets, twitch, r2, email, events, shared, template-version)
• Each module contains a Nest module definition, GraphQL resolvers or REST controllers, services, DTOs, models (Mongoose schemas)
• events.module contains an EventsGateway (Socket.IO), handlers, Twitch event adapters (twurple)
• auth.module uses Passport + JWT strategies, guards, and decorators
• Data layer: Mongoose is used (models under each module).
• Testing: unit and e2e tests under test/.
README for technical stack & architecture hints
• Framework: NestJS
• API: GraphQL via Apollo Server (queries, mutations, subscriptions)
• DB: MongoDB + Mongoose
• Auth: JWT + Passport
• Real‑time: Socket.IO gateway
• External integrations: Twurple (Twitch), email service, Cloudflare R2, Stripe (payments), GeoIP‑Lite
Core components
a. Clients
• Web client(s) or overlay front‑end (GraphQL client over HTTP for queries/mutations, WebSocket client for subscriptions/events)
• Admin/dashboard UI (if any)
b. API Server (NestJS + Apollo)
• GraphQL Resolver Layer
• Service Layer (business logic modules)
• Data Access Layer (Mongoose models)
• Authentication subsystem (Passport + JWT strategy + Guards + Decorators)
• Events Gateway (Socket.IO)
c. Database
• MongoDB cluster (collections per module: users, sessions, templates, etc.)
d. External services
• Twitch API (via Twurple)
• Email provider (SMTP or third‑party API)
• File storage (Cloudflare R2)
• Payment gateway (e.g., Stripe)
• (Optional) GeoIP lookup module
e. Deployment & Infrastructure
• Docker container & docker‑compose / Railway deployment
• Environment variables / .env
Relationships & data‑flow
• Clients → GraphQL endpoint (HTTP POST) → Resolvers → Services → Mongoose → MongoDB
• Clients ↔ WebSocket endpoint → EventsGateway → EventHandlers → Clients
• Resolvers/Services ↔ External services (Twitch API calls, email sends, payment processing, file uploads)
• Auth guard intercepts incoming requests, validates JWT with Passport strategy, injects user context
Architectural patterns & principles
• Modular Monolith: segmented by feature modules
• Layered Architecture: Controller/Resolver → Service → Repository (Mongoose models)
• Dependency Injection (via NestJS)
• Event‑Driven (Socket.IO + internal event bus)
• Single Responsibility & Separation of Concerns (each module owns its domain)
• Notation of data stores (MongoDB) and caches (if any)
• Cloud/infrastructure symbols for Docker/Railway