# staroverlay/backend architecture

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

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

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Clients Layer
    subgraph "Clients"
        direction TB
        WebClient["Web & Overlay UI"]:::clients
        AdminUI["Admin Dashboard"]:::clients
    end

    %% API Server Layer
    subgraph "API Server (NestJS + Apollo)"
        direction TB
        Main["main.ts"]:::api
        AppModule["AppModule"]:::api

        subgraph "Authentication Subsystem"
            direction TB
            AuthModule["AuthModule"]:::auth
            JWTStrategy["JWT Strategy"]:::auth
            Guards["Auth Guards"]:::auth
            Decorators["Auth Decorators"]:::auth
        end

        subgraph "GraphQL Resolver Layer"
            direction TB
            Resolvers["GraphQL Resolvers"]:::resolver
        end

        subgraph "Service Layer"
            direction TB
            Services["Services"]:::service
        end

        subgraph "Data Access Layer"
            direction TB
            Models["Mongoose Models & Schemas"]:::dal
        end

        subgraph "Real‑Time Events"
            direction TB
            EventsGateway["EventsGateway (Socket.IO)"]:::realtime
        end
    end

    %% Database
    MongoDB["MongoDB Cluster"]:::db

    %% External Services
    subgraph "External Services"
        direction TB
        TwitchAPI["Twitch API (Twurple)"]:::external
        EmailProvider["Email Provider"]:::external
        R2Storage["Cloudflare R2"]:::external
        StripeAPI["Stripe"]:::external
    end

    %% Infrastructure
    subgraph "Deployment & Infrastructure"
        direction TB
        DockerCompose["Docker & Compose"]:::infra
        EnvFiles[".env.sample, CI Config"]:::infra
        RailwayDeploy["Railway.toml"]:::infra
    end

    %% Connections
    WebClient -->|HTTP GraphQL| Resolvers
    AdminUI -->|HTTP GraphQL| Resolvers
    WebClient -->|WebSocket Subscription| EventsGateway

    Main --> AppModule
    AppModule --> AuthModule
    AppModule --> Resolvers
    AppModule --> Services
    AppModule --> Models
    AppModule --> EventsGateway

    Resolvers -->|"calls"| Services
    Resolvers -->|"uses"| AuthModule
    Services -->|"reads/writes"| Models
    Models --> MongoDB

    JWTStrategy --> Guards
    Guards -->|validates| Resolvers

    Services -->|Twitch calls| TwitchAPI
    Services -->|send email| EmailProvider
    Services -->|file operations| R2Storage
    Services -->|payments| StripeAPI

    EventsGateway -->|push events| WebClient

    DockerCompose --> Main
    EnvFiles --> Main
    RailwayDeploy --> Main

    %% Click Events
    click Main "https://github.com/staroverlay/backend/blob/main/src/main.ts"
    click AppModule "https://github.com/staroverlay/backend/blob/main/src/app.module.ts"
    click AuthModule "https://github.com/staroverlay/backend/blob/main/src/auth/auth.module.ts"
    click JWTStrategy "https://github.com/staroverlay/backend/blob/main/src/auth/strategies/jwt.stategy.ts"
    click Guards "https://github.com/staroverlay/backend/blob/main/src/auth/guards/*.ts"
    click Decorators "https://github.com/staroverlay/backend/blob/main/src/decorators/auth-token.decorator.ts"
    click Decorators "https://github.com/staroverlay/backend/blob/main/src/decorators/current-user.decorator.ts"
    click Resolvers "https://github.com/staroverlay/backend/blob/main/src/modules/**/*.resolver.ts"
    click Services "https://github.com/staroverlay/backend/blob/main/src/modules/**/*.service.ts"
    click Models "https://github.com/staroverlay/backend/blob/main/src/modules/**/models/*.ts"
    click Models "https://github.com/staroverlay/backend/blob/main/src/modules/**/schema/*.ts"
    click EventsGateway "https://github.com/staroverlay/backend/blob/main/src/modules/events/events.gateway.ts"
    click TwitchAPI "https://github.com/staroverlay/backend/blob/main/src/modules/twitch/twitch.service.ts"
    click EmailProvider "https://github.com/staroverlay/backend/blob/main/src/modules/email/email.service.ts"
    click R2Storage "https://github.com/staroverlay/backend/blob/main/src/modules/r2/r2.service.ts"
    click StripeAPI "https://github.com/staroverlay/backend/blob/main/src/modules/payments/payments.service.ts"
    click DockerCompose "https://github.com/staroverlay/backend/tree/main/Dockerfile"
    click EnvFiles "https://github.com/staroverlay/backend/blob/main/.env.sample"
    click RailwayDeploy "https://github.com/staroverlay/backend/blob/main/railway.toml"

    %% Styles
    classDef clients fill:#f9f,stroke:#333,stroke-width:1px
    classDef api fill:#bbf,stroke:#333,stroke-width:1px
    classDef auth fill:#aaf,stroke:#333,stroke-width:1px
    classDef resolver fill:#8cf,stroke:#333,stroke-width:1px
    classDef service fill:#bfb,stroke:#333,stroke-width:1px
    classDef dal fill:#afa,stroke:#333,stroke-width:1px
    classDef realtime fill:#c9f,stroke:#333,stroke-width:1px
    classDef db fill:#faa,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5
    classDef external fill:#fed,stroke:#333,stroke-width:1px
    classDef infra fill:#ddd,stroke:#333,stroke-width:1px
```
