How maddyunderstars/shoot works
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.