# maddyunderstars/shoot architecture

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

- Interactive diagram: https://gitdiagram.com/maddyunderstars/shoot
- Repository: https://github.com/maddyunderstars/shoot

## Overview

##### Main Components
- CLI Module – Located under src/cli: This handles command-line interactions like generating keys, adding users, and instance configuration.
- HTTP Server/API – Found in src/http: It defines the RESTful API endpoints for user authentication, guild management, channels, messages, and federated interactions. It also includes middleware (auth, error-handling, rate limiting) and well-known endpoints (webfinger, nodeinfo, host-meta) that support federation.
- Gateway Module – Under src/gateway: Manages long-lived connections, WebSocket handling (connection, messaging, heartbeats), and communication protocols for real-time messaging.
- Media Module – Under src/media: Contains logic for voice and video chat support, as well as integration with Janus media server. It similarly includes WebSocket handling and event processing.
- Core Entities and Business Logic – Under src/entity and src/util/entity: These define the data models such as users, channels, guilds, messages, sessions, and relationships. They also incorporate migrations and database abstractions.
- ActivityPub/Federation Utilities – Found under src/util/activitypub: Contains handlers, transformers, and utilities for enabling federation with other ActivityPub networks.
- Storage and Config – Utilities (like src/util/database, src/util/config, and src/util/storage) are essential for abstracting database interactions, configuration management (using the config package), and file/S3 storage.

##### Relationships and Interactions
- The CLI interacts with core functionality (like generation of keys and user creation), triggering actions within the HTTP server or directly updating configuration and credentials.
- The HTTP API serves as an external interface where incoming HTTP requests interact with backend logic. It calls middleware for authentication, then orchestrates data interactions with the database using the entity models.
- The Gateway provides a persistent WebSocket layer for real-time messaging. It communicates with the HTTP server to synchronize state (like user presence) and uses defined handlers (identify, heartbeat, etc.) to maintain connections.
- The Media sub-system, with its WebSocket connections and integration with Janus, handles voice/video stream negotiation. It usually interfaces with both the HTTP API (for session initiation) and the Gateway for call-related events.
- ActivityPub utilities serve as a bridge for federation. They transform internal data (users, messages, invites) and communicate with external federated services. This integration occurs across both HTTP and background tasks.
- Database and storage components underpin the entire system by persisting state (users, messages, guilds). They can be represented as a shared resource consumed by various modules.

##### Important Architectural Patterns and Design Principles
- Modular Design: Separation of concerns is evident – with different directories handling API routes, real-time gateway connections, media communications, and federation.
- RESTful API and WebSockets: Two distinct communication methods are used. REST for traditional web interactions and WebSockets for immediate, persistent messaging.
- Configuration and Extensibility: With CLI utilities and configuration via JSON files, the design supports dynamic management and expansion of features.

##### Technologies, Frameworks, and External Integrations
- Node.js (v18+): The project runs on Node.js.
- PostgreSQL: Used as the primary relational database.
- Janus Media Server: (Optional) for voice/video capabilities.
- Redis (Optional): For inbound federation queue.
- WebSocket: Used in both gateway and media layers.
- ActivityPub: As part of the federation mechanism.
- Ava: Testing framework for unit and integration tests.

##### Final Touches for the Principal Software Engineer
- Detail the internal components and their interactions: how API requests are processed, how the Gateway maintains persistent sessions, and how media calls are routed via the Janus integration.
- Each major component/module.
- Notations of critical integrations like ActivityPub communications, optional Redis queues, and Janus media server connectivity.
- Keep it as detailed as possible so that every architectural decision and dependency is transparent.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Client Layer"
        EClients("External Clients"):::external
        EFed("External Fediverse"):::external
    end

    subgraph "Backend Services"
        CLI("CLI Module"):::cli
        HTTP("HTTP Server/API"):::http
        Gateway("Gateway Module"):::gateway
        Media("Media Module"):::media
        subgraph "Core Entities"
            EntityModels("Entity Models"):::entity
            EntityUtils("Entity Utils"):::entity
        end
        ActivityPub("ActivityPub Utilities"):::activitypub
    end

    subgraph "Infrastructure"
        Database("Database"):::infrastructure
        Config("Configuration"):::infrastructure
        Storage("Storage"):::infrastructure
        Janus("Janus Media Server"):::externalService
        Redis("Redis Queue"):::externalService
    end

    %% Connections from Client Layer to Backend
    EClients -->|"HTTPRequests"| HTTP
    EFed ---|"federation_response"| ActivityPub

    %% Interaction between CLI and backend
    CLI -->|"triggers"| HTTP
    CLI -->|"updates"| EntityModels

    %% HTTP interactions with core and infrastructure
    HTTP -->|"calls"| EntityModels
    HTTP -->|"persists"| Database
    HTTP -->|"uses"| Config
    HTTP -->|"uses"| Storage
    HTTP -->|"federation"| ActivityPub

    %% ActivityPub interacts with external fediverse and optional Redis
    ActivityPub -->|"communicates"| EFed
    ActivityPub -->|"queues"| Redis

    %% Gateway and Media real-time interaction
    HTTP <-->|"sync"| Gateway
    Gateway <-->|"sync"| Media
    Media -->|"session_init"| HTTP
    Media -->|"negotiates"| Janus

    %% Core Entities persistence
    EntityModels -->|"stores_data"| Database

    %% Click Events
    click CLI "https://github.com/maddyunderstars/shoot/tree/main/src/cli"
    click HTTP "https://github.com/maddyunderstars/shoot/tree/main/src/http"
    click Gateway "https://github.com/maddyunderstars/shoot/tree/main/src/gateway"
    click Media "https://github.com/maddyunderstars/shoot/tree/main/src/media"
    click EntityModels "https://github.com/maddyunderstars/shoot/tree/main/src/entity"
    click EntityUtils "https://github.com/maddyunderstars/shoot/tree/main/src/util/entity"
    click ActivityPub "https://github.com/maddyunderstars/shoot/tree/main/src/util/activitypub"
    click Database "https://github.com/maddyunderstars/shoot/tree/main/src/util/database"
    click Config "https://github.com/maddyunderstars/shoot/blob/main/src/util/config.ts"
    click Storage "https://github.com/maddyunderstars/shoot/tree/main/src/util/storage"

    %% Styles
    classDef external fill:#FAD7A0,stroke:#C0392B,stroke-width:2px;
    classDef cli fill:#AED6F1,stroke:#1F618D,stroke-width:2px;
    classDef http fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef gateway fill:#A9DFBF,stroke:#229954,stroke-width:2px;
    classDef media fill:#F5B7B1,stroke:#922B21,stroke-width:2px;
    classDef entity fill:#D7BDE2,stroke:#7D3C98,stroke-width:2px;
    classDef activitypub fill:#FCF3CF,stroke:#B7950B,stroke-width:2px;
    classDef infrastructure fill:#D5F5E3,stroke:#28B463,stroke-width:2px;
    classDef externalService fill:#D6EAF8,stroke:#2471A3,stroke-width:2px;
```
