Revolt

Stoat is the self‑hosted implementation of Revolt’s modern communication platform, engineered to run as a cohesive stack comprising a Rust‑based backend, a TypeScript/React web client, and auxiliary services for file storage and image proxying. From a developer’s standpoint it is essentially a micro‑service architecture that exposes a well‑documented REST/GraphQL API and WebSocket endpoints for real‑time interaction. The core server is written in Rust, leveraging the Actix‑Web framework for high‑throughput request handling and Tokio for async runtime. The web client is a single‑page application built with Vite, React, and Redux Toolkit, communicating over HTTPS via the same domain as the API to simplify CORS handling.

Architecture & Technical Stack

• Backend: Rust (Actix‑Web, Tokio), compiled to a single statically linked binary. The API layer supports both REST and GraphQL, with real‑time events delivered over WebSockets (JSON‑encoded). Authentication is JWT‑based and can be integrated with external OAuth providers.
• Database: MongoDB (v4.2+), used for user accounts, channel metadata, message history, and file indexes. The schema is flexible but heavily typed through Rust’s serde structs; migrations are handled via the migrate crate.
• File Server: A lightweight Rust service that serves static uploads, optionally behind a CDN. It accepts multipart uploads and stores them in an S3‑compatible bucket or local filesystem.
• Image Proxy: Dedicated proxy that resizes and caches images on demand, reducing bandwidth for clients. Implemented in Rust with the image crate and a local LRU cache.
• Containerization: Each component can be run as an isolated Docker container. The repository provides a docker-compose.yml that orchestrates the backend, web client (served via Nginx), file server, and image proxy. For production, the stack is often deployed behind a reverse‑proxy like Nginx or Traefik with TLS termination.

Core Capabilities & APIs

Stoat exposes a rich set of endpoints that mirror the original Revolt API:

• Messaging: Create, edit, delete messages; support for embeds, attachments, and reactions. Real‑time delivery via WebSocket message events.
• Channels & Permissions: Fine‑grained permission system per channel, role hierarchy, and integration hooks for bots.
• Users & Profiles: User creation, authentication flows, presence updates, and profile customization. Supports OAuth2 callbacks for third‑party login.
• Bots & Webhooks: Developers can register bots that receive events over a dedicated WebSocket or HTTP webhook. The API allows bot‑specific token generation and permission scoping.
• Search & Moderation: Full‑text search over messages using MongoDB’s text indexes, plus moderation endpoints for bans, mutes, and message deletions.

The API is documented in OpenAPI format and available at /docs. TypeScript type definitions can be generated automatically, enabling strong typing in client libraries.

Deployment & Infrastructure

Stoat is designed for straightforward self‑hosting on any Linux VM with at least 2 vCPUs and 2 GB RAM. The Docker images are built for linux/amd64 only, though the backend binary can be compiled for other architectures if needed. For scalability:

• Horizontal Scaling: Multiple backend instances can be load‑balanced behind Traefik or Nginx, sharing a single MongoDB replica set. The stateless nature of the API allows easy scaling.
• Database Resilience: MongoDB should be run as a replica set; the self‑hosted guide includes instructions for setting up a local 3‑node replica or connecting to an external managed service.
• Persistent Storage: File uploads are stored in a dedicated directory or S3 bucket; the image proxy caches resized images on disk. These volumes should be backed up regularly.

Integration & Extensibility

Stoat’s plugin architecture is still evolving, but developers can extend functionality through:

• Custom Webhooks: Subscribe to channel events and trigger external services.
• OAuth2 Providers: Add new authentication backends via the settings API.
• Reverse‑Proxy Rules: Configure Traefik rules to expose additional endpoints or custom subdomains.
• WebSocket Extensions: Inject middleware into the Actix‑Web pipeline to add custom headers or modify payloads.

Because all services are open source, you can fork the repository, patch the backend, or replace the web client with a custom UI that consumes the same API.

Developer Experience

The repository ships with comprehensive documentation: a detailed README, an FAQ on the developer site, and inline code comments. The Docker compose files are ready‑to‑run, while the backend’s Rust code follows idiomatic patterns with clear error handling and logging. Community support is active on GitHub Discussions, Discord, and the Revolt developer forum, where contributors frequently review pull requests and address security advisories promptly.

Use Cases

• Private Communities: Host a GDPR‑compliant chat for an organization or club, controlling user data and access.
• Custom Bot Ecosystem: Build bots that interact with the API, leveraging webhooks for real‑time processing.
• Educational Platforms: Deploy a chat server for classrooms or online courses, integrating with existing authentication systems.
• Event‑Driven Microservices: Use the WebSocket events to trigger downstream services (e.g., analytics