# polyphony-chat/symfonia architecture

> Architecture diagram of the GitHub repository polyphony-chat/symfonia, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2024-12-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/polyphony-chat/symfonia
- Repository: https://github.com/polyphony-chat/symfonia

## Overview

##### Main System Components

a) API Layer (HTTP API Server)
- Authentication services (/src/api/routes/auth)
- User management (/src/api/routes/users)
- Guild/Server management (/src/api/routes/guilds)
- Channel management (/src/api/routes/channels)
- Policy management (/src/api/routes/policies)

b) WebSocket Gateway
- Connection handling (/src/gateway/establish_connection.rs)
- Event dispatching (/src/gateway/types/dispatchevent.rs)
- Heartbeat management (/src/gateway/heartbeat.rs)

c) CDN Server
- File storage and delivery system (/src/cdn)

d) Database Layer
- PostgreSQL database
- Entity models (/src/database/entities)
- Migration management (/migrations)

##### Component Relationships

**Client Layer (External)**
- ↕
**┌──────────────────────────────┐**
- Load Balancer/Proxy      │
- ┘
- ↕
**┌──────────────────────────────┐**
- API Server    │   Gateway  │
- (HTTP/REST)    │ (WebSocket)│
- ┘
- ↕               ↕
**┌──────────────────────────────┐**
- Database Layer (PostgreSQL)│
- ┘
- ↕
**┌──────────────────────────────┐**
- CDN Server           │
- ┘

##### Detailed Component Breakdown

API Server:
- Authentication middleware
- Route handlers
- Permission guards
- Current user context

Gateway:
- Connection establishment
- Event handling
- Heartbeat mechanism
- Session management

Database:
- Entity relationships
- Migration flow
- Data models
- Foreign key constraints

##### Technical Stack Indicators

Following technologies:
- Rust (primary language)
- PostgreSQL (database)
- SQLx (database toolkit)
- WebSocket protocol
- HTTP/REST APIs

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph Client["Client Layer"]
        C1[External Clients]
    end

    subgraph LoadBalancer["Load Balancer Layer"]
        LB[Proxy/Load Balancer]
    end

    subgraph APIGateway["API & Gateway Layer"]
        subgraph API["API Server"]
            Auth["Authentication"]:::security
            Users["User Management"]:::api
            Guilds["Guild Management"]:::api
            Channels["Channel Management"]:::api
            Policies["Policy Management"]:::api
            AuthMid["Auth Middleware"]:::security
            PermGuard["Permission Guards"]:::security
        end

        subgraph WS["WebSocket Gateway"]
            Conn["Connection Handler"]:::gateway
            Event["Event Dispatcher"]:::gateway
            Heart["Heartbeat Manager"]:::gateway
            GTask["Gateway Task"]:::gateway
        end
    end

    subgraph DB["Database Layer"]
        Postgres[(PostgreSQL)]:::database
        Models["Entity Models"]:::database
        Migration["Migrations"]:::database
        DBCore["Database Core"]:::database
        UserEntity["User Entity"]:::database
        GuildEntity["Guild Entity"]:::database
        ChannelEntity["Channel Entity"]:::database
        MessageEntity["Message Entity"]:::database
    end

    subgraph CDN["CDN Layer"]
        CDNServer["CDN Server"]:::cdn
    end

    subgraph Util["Utility Services"]
        Email["Email Service"]:::utility
        Token["Token Management"]:::utility
    end

    %% Connections
    C1 --> LB
    LB --> API
    LB --> WS
    API --> DB
    WS --> DB
    DB --> CDN
    API --> Util
    WS --> Util

    %% Click Events
    click Auth "https://github.com/polyphony-chat/symfonia/tree/main//src/api/routes/auth/"
    click Users "https://github.com/polyphony-chat/symfonia/tree/main//src/api/routes/users/"
    click Guilds "https://github.com/polyphony-chat/symfonia/tree/main//src/api/routes/guilds/"
    click Channels "https://github.com/polyphony-chat/symfonia/tree/main//src/api/routes/channels/"
    click Policies "https://github.com/polyphony-chat/symfonia/tree/main//src/api/routes/policies/"
    click AuthMid "https://github.com/polyphony-chat/symfonia/blob/main//src/api/middleware/authentication.rs"
    click PermGuard "https://github.com/polyphony-chat/symfonia/blob/main//src/api/middleware/permission_guard.rs"
    click Conn "https://github.com/polyphony-chat/symfonia/blob/main//src/gateway/establish_connection.rs"
    click Event "https://github.com/polyphony-chat/symfonia/blob/main//src/gateway/types/dispatchevent.rs"
    click Heart "https://github.com/polyphony-chat/symfonia/blob/main//src/gateway/heartbeat.rs"
    click GTask "https://github.com/polyphony-chat/symfonia/blob/main//src/gateway/gateway_task.rs"
    click CDNServer "https://github.com/polyphony-chat/symfonia/blob/main//src/cdn/mod.rs"
    click Models "https://github.com/polyphony-chat/symfonia/tree/main//src/database/entities/"
    click Migration "https://github.com/polyphony-chat/symfonia/tree/main//migrations/"
    click DBCore "https://github.com/polyphony-chat/symfonia/blob/main//src/database/mod.rs"
    click UserEntity "https://github.com/polyphony-chat/symfonia/blob/main//src/database/entities/user.rs"
    click GuildEntity "https://github.com/polyphony-chat/symfonia/blob/main//src/database/entities/guild.rs"
    click ChannelEntity "https://github.com/polyphony-chat/symfonia/blob/main//src/database/entities/channel.rs"
    click MessageEntity "https://github.com/polyphony-chat/symfonia/blob/main//src/database/entities/message.rs"
    click Email "https://github.com/polyphony-chat/symfonia/tree/main//src/util/email/"
    click Token "https://github.com/polyphony-chat/symfonia/blob/main//src/util/token.rs"

    %% Styling
    classDef api fill:#3498db
    classDef security fill:#e74c3c
    classDef gateway fill:#2ecc71
    classDef database fill:#f1c40f
    classDef cdn fill:#9b59b6
    classDef utility fill:#95a5a6

    %% Legend
    subgraph Legend
        API_L["API Component"]:::api
        SEC_L["Security Component"]:::security
        GW_L["Gateway Component"]:::gateway
        DB_L["Database Component"]:::database
        CDN_L["CDN Component"]:::cdn
        UTIL_L["Utility Component"]:::utility
    end
```
