# polyphony-chat/chorus architecture

> Architecture diagram of the GitHub repository polyphony-chat/chorus, 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/chorus
- Repository: https://github.com/polyphony-chat/chorus

## Overview

##### Main Components

a) Core Library Components:
- Instance Manager
- Authentication System
- Gateway System
- Voice System
- Rate Limiter
- API Endpoints Handler

b) External Interfaces:
- Chat Services (Spacebar/Discord/Polyphony)
- WebSocket Connections
- UDP Connections (for voice)
- HTTP REST APIs

**┌─────────────────────────────────────────────────────────────┐**
- Client Applications                      │
- ┘
- ▲

**┌─────────────────────────────────────────────────────────────┐**
- Chorus Library API                       │
- ┬──────────────┬─────────────┬─────────────────┤
- Instance   │    Gateway   │    Voice    │   API Endpoints  │
- Manager    │    System    │    System   │     Handler      │
- ┴──────────────┴─────────────┴─────────────────┤
- Core Services                           │
- ┬──────────────┬─────────────┬─────────────────┤
- Auth      │ Rate Limiter │ WebSocket   │    UDP          │
- Manager    │              │ Backend     │   Backend       │
- ┴──────────────┴─────────────┴─────────────────┘
- ▲

**┌─────────────────────────────────────────────────────────────┐**
- External Chat Services                      │
- (Spacebar / Discord / Polyphony Servers)             │
- ┘

##### Component Details

Instance Manager:
- Handles multiple server connections
- Manages instance configuration
- Coordinates authentication and session management

Gateway System:
- WebSocket connection management
- Event handling and distribution
- Heartbeat maintenance
- Connection state management

Voice System:
- UDP communication
- Voice data encryption
- Session management
- Backend implementations (tokio/wasm)

API Endpoints Handler:
- REST API interactions
- Request/response management
- Error handling
- Type-safe interfaces

##### Important Relationships

- Bidirectional communication between Gateway and External Services
- One-way dependencies from Client Applications to Library API
- Internal communication between components
- Rate limiter intercepting API calls
- Authentication flow through the system

##### Additional Elements

- Version compatibility information
- Platform-specific implementations
- Error handling paths
- Rate-limited pathways

##### Implementation Notes

- Notes about minimum Rust version requirements
- Thread boundaries and async contexts

- UML notation
- Custom styling
- Layered architecture representation
- Clear typography
- Export to vector formats

Remember to maintain a balance between detail and clarity, focusing on the key architectural decisions while avoiding overwhelming technical minutiae.

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph Client["Client Applications"]
        CA[Client App]
    end

    subgraph Library["Chorus Library API"]
        subgraph Core["Core Components"]
            IM["Instance Manager"]:::core
            GS["Gateway System"]:::core
            VS["Voice System"]:::core
            AH["API Endpoints Handler"]:::core
        end

        subgraph Services["Core Services"]
            AM["Authentication System"]:::service
            RL["Rate Limiter"]:::service
            WB["WebSocket Backend"]:::service
            UB["UDP Backend"]:::service
        end
    end

    subgraph External["External Chat Services"]
        SB["Spacebar"]:::external
        DC["Discord"]:::external
        PL["Polyphony"]:::external
    end

    %% Relationships
    CA --> IM
    IM --> AM
    IM --> GS
    IM --> VS
    IM --> AH
    
    GS --> WB
    VS --> UB
    AH --> RL
    
    WB --> |WebSocket| External
    UB --> |UDP| External
    AH --> |HTTP REST| External
    
    %% Click Events
    click IM "https://github.com/polyphony-chat/chorus/blob/main/src/instance.rs"
    click AM "https://github.com/polyphony-chat/chorus/blob/main/src/api/auth/mod.rs"
    click GS "https://github.com/polyphony-chat/chorus/blob/main/src/gateway/gateway.rs"
    click VS "https://github.com/polyphony-chat/chorus/blob/main/src/voice/mod.rs"
    click RL "https://github.com/polyphony-chat/chorus/blob/main/src/ratelimiter.rs"
    click AH "https://github.com/polyphony-chat/chorus/blob/main/src/api/mod.rs"
    click WB "https://github.com/polyphony-chat/chorus/blob/main/src/gateway/backends/mod.rs"
    click UB "https://github.com/polyphony-chat/chorus/blob/main/src/voice/udp/backends/mod.rs"

    %% Styling
    classDef core fill:#3498db,stroke:#2980b9,color:white
    classDef service fill:#95a5a6,stroke:#7f8c8d,color:white
    classDef external fill:#2ecc71,stroke:#27ae60,color:white
    
    %% Legend
    subgraph Legend
        L1["Core Components"]:::core
        L2["Services"]:::service
        L3["External Systems"]:::external
    end
```
