# spacebarchat/server architecture

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

- Interactive diagram: https://gitdiagram.com/spacebarchat/server
- Repository: https://github.com/spacebarchat/server

## Overview

##### Main Components
The system architecture should be divided into four main server components:

a. HTTP API Server (src/api)
- Entry point: src/api/Server.ts
- REST endpoints organized by resource types (users, guilds, channels, etc.)
- Middleware chain (Authentication, CORS, RateLimit, etc.)

b. WebSocket Gateway Server (src/gateway)
- Entry point: src/gateway/Server.ts
- Event handling system
- Opcodes handling (Heartbeat, Identify, etc.)
- Connection management

c. CDN Server (src/cdn)
- Entry point: src/cdn/Server.ts
- File storage systems (FileStorage, S3Storage)
- Asset routes (attachments, avatars, etc.)

d. Utility and Database Layer (src/util)
- Entity models
- Database migrations
- Shared utilities

##### External Integrations
Connections to:
- Multiple database types (PostgreSQL, MySQL, MariaDB)
- External services (email providers, OAuth connections)
- Storage systems (local/S3)

##### Key Relationships and Flows

a. Client Communication Flow:
- Client → API Server (REST calls)
- Client ↔ Gateway Server (WebSocket)
- Client → CDN Server (Asset requests)

b. Internal Communication:
- API Server ↔ Database
- Gateway Server ↔ Database
- CDN Server ↔ Storage Systems

##### Authentication and Security Layer
- Authentication middleware
- Rate limiting
- CORS handling
- MFA systems (TOTP, WebAuthn)

##### Feature Modules
Related components:
- User Management
- Guild/Server Management
- Messaging Systems
- Voice/WebRTC
- OAuth2/Applications

##### Data Flow Patterns
- Real-time communication (WebSocket)
- REST API calls
- File transfers
- Database operations

##### Scaling Components
Areas that can be horizontally scaled:
- API servers
- Gateway nodes
- CDN endpoints
- Database clusters

##### Supporting Systems
Auxiliary components:
- Email service integration
- Translation/localization system
- Configuration management
- Migration handling

- Rectangles for services
- Clouds for external services
- Hexagons for security components

Remember to:
- Related components visually
- Primary and secondary data flows
- Scalability points
- Security boundaries
- External service dependencies

This architecture should emphasize the project's goal of being a drop-in replacement for Discord's backend while maintaining compatibility with existing clients and bots.

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph Client
        C[Client Applications]
    end

    subgraph "API Layer"
        AS["API Server"]:::apiserver
        M1["Authentication"]:::middleware
        M2["Rate Limiting"]:::middleware
        M3["CORS"]:::middleware
        
        AS --> M1 & M2 & M3
        
        subgraph "API Routes"
            R1["User Routes"]:::route
            R2["Guild Routes"]:::route
            R3["Channel Routes"]:::route
            R4["Auth Routes"]:::route
        end
        
        M1 & M2 & M3 --> R1 & R2 & R3 & R4
    end

    subgraph "Gateway Layer"
        GS["WebSocket Gateway"]:::gateway
        E1["Event Handlers"]:::event
        E2["Opcodes Handler"]:::event
        E3["Connection Manager"]:::event
        
        GS --> E1 & E2 & E3
    end

    subgraph "CDN Layer"
        CS["CDN Server"]:::cdn
        S1["File Storage"]:::storage
        S2["S3 Storage"]:::storage
        AR["Asset Routes"]:::route
        
        CS --> S1 & S2
        CS --> AR
    end

    subgraph "Core Layer"
        DB[(Database)]:::database
        EM["Entity Models"]:::core
        MG["Migrations"]:::core
        CF["Config"]:::core
        
        EM --> DB
        MG --> DB
    end

    subgraph "Supporting Systems"
        ES["Email Service"]:::support
        TS["Translation System"]:::support
        MFA["MFA System"]:::security
        OAuth["OAuth Service"]:::security
    end

    C --> AS
    C <--> GS
    C --> CS
    
    AS <--> DB
    GS <--> DB
    CS <--> DB
    
    AS --> ES
    AS --> OAuth
    AS --> MFA

    %% Click Events
    click AS "https://github.com/spacebarchat/server/blob/master/src/api/Server.ts"
    click M1 "https://github.com/spacebarchat/server/blob/master/src/api/middlewares/Authentication.ts"
    click M2 "https://github.com/spacebarchat/server/blob/master/src/api/middlewares/RateLimit.ts"
    click M3 "https://github.com/spacebarchat/server/blob/master/src/api/middlewares/CORS.ts"
    click R4 "https://github.com/spacebarchat/server/tree/master/src/api/routes/auth/"
    click GS "https://github.com/spacebarchat/server/blob/master/src/gateway/Server.ts"
    click E1 "https://github.com/spacebarchat/server/tree/master/src/gateway/events/"
    click E2 "https://github.com/spacebarchat/server/tree/master/src/gateway/opcodes/"
    click CS "https://github.com/spacebarchat/server/blob/master/src/cdn/Server.ts"
    click S1 "https://github.com/spacebarchat/server/blob/master/src/cdn/util/FileStorage.ts"
    click S2 "https://github.com/spacebarchat/server/blob/master/src/cdn/util/S3Storage.ts"
    click AR "https://github.com/spacebarchat/server/tree/master/src/cdn/routes/"
    click EM "https://github.com/spacebarchat/server/tree/master/src/util/entities/"
    click MG "https://github.com/spacebarchat/server/tree/master/src/util/migration/"
    click CF "https://github.com/spacebarchat/server/tree/master/src/util/config/"
    click ES "https://github.com/spacebarchat/server/tree/master/src/util/util/email/"
    click TS "https://github.com/spacebarchat/server/tree/master/assets/locales/"
    click MFA "https://github.com/spacebarchat/server/tree/master/src/api/routes/auth/mfa/"
    click OAuth "https://github.com/spacebarchat/server/tree/master/src/connections/"

    %% Styling
    classDef apiserver fill:#2374ab
    classDef gateway fill:#2a9d8f
    classDef cdn fill:#e76f51
    classDef database fill:#457b9d
    classDef middleware fill:#a8dadc
    classDef route fill:#f1faee
    classDef event fill:#95d5b2
    classDef storage fill:#ffd7ba
    classDef core fill:#b388eb
    classDef support fill:#caffbf
    classDef security fill:#ffadad
```
