SAMA

SAMA (Simple but Advanced Messaging Alternative) is a self‑hosted WebSocket‑based chat server designed to replace the ubiquitous XMPP protocol with a lightweight, high‑performance alternative. Built on Node.js and powered by the ultra‑fast uWebSockets.js library, SAMA delivers sub‑millisecond latency for real‑time messaging while keeping the memory footprint low enough to run comfortably on a single VM or a Docker container. The server exposes a RESTful JSON API for user, conversation, message, activity, address‑book and push‑notification management, making it straightforward for developers to integrate SAMA into existing backend stacks or build custom clients.

Architecture & Technical Stack

• Core Runtime: Node.js (v18+) with uWebSockets.js as the WebSocket engine, chosen for its superior throughput and minimal CPU usage compared to native ws or Socket.io.
• Data Persistence: MongoDB (v6+) stores user profiles, conversation metadata, message history, and address‑book entries. The schema is intentionally flexible to accommodate future extensions without migrations.
• Cache & Pub/Sub: Redis (v7+) handles session tokens, rate‑limiting counters, and a Pub/Sub channel for inter‑process message routing, enabling horizontal scaling across multiple server instances.
• Infrastructure: Docker images are provided for quick deployment; the repo includes a docker-compose.yml that spins up the server, MongoDB, and Redis in isolated containers. For production, the documentation recommends deploying behind an NGINX reverse proxy with TLS termination and a load balancer to distribute WebSocket connections.
• Cloud Compatibility: Native support for AWS (ECS/EKS, RDS, ElastiCache) is documented, but the stack runs equally well on any cloud or bare‑metal host.

Core Capabilities & APIs

SAMA’s API surface mirrors the data model:

Each endpoint follows REST conventions and returns JSON; authentication is JWT‑based, issued by the server after successful login. WebSocket connections are authenticated with a short‑lived token and then upgrade to a persistent channel for low‑latency events.

Deployment & Infrastructure

SAMA is intentionally lightweight to support self‑hosting on a single instance:

• Memory Footprint: A minimal Node.js build with uWebSockets.js consumes ~50 MB; adding MongoDB and Redis pushes the total to ~200–300 MB per container.
• Scalability: Horizontal scaling is achieved by running multiple server containers behind a load balancer. Redis Pub/Sub synchronizes message delivery across instances, while MongoDB’s replica set ensures data durability.
• Containerization: The Docker image is Alpine‑based, making it suitable for CI/CD pipelines. Kubernetes manifests are available in the docs for deploying as a StatefulSet with persistent volumes.
• High Availability: The server’s stateless design (except for session tokens in Redis) means any instance can handle a new client without state migration.

Integration & Extensibility

Developers can extend SAMA in several ways:

• Webhooks: External services can subscribe to conversation or message events via configurable webhook URLs, enabling real‑time analytics or integrations with CRMs.
• Plugin System: The server exposes a simple plugin API; developers can write Node.js modules that hook into lifecycle events (e.g., message pre‑send validation, custom routing).
• Custom Protocols: Because the core is built on uWebSockets.js, adding a new binary protocol (e.g., for file transfer or gaming lobbies) is straightforward.
• SDKs: Official JavaScript and Flutter SDKs wrap the REST API and WebSocket events, reducing boilerplate for client developers.

Developer Experience

SAMA’s documentation is comprehensive: an API reference, step‑by‑step deployment guides, and Medium articles for each endpoint. The GitHub repo follows semantic versioning; issues are triaged quickly, and the community Slack channel provides real‑time support. Configuration is driven by environment variables (SAMA_DB_URI, REDIS_URL, JWT_SECRET), making it easy to adopt in CI/CD pipelines or cloud environments.

Use Cases

• Enterprise Chat: Replace legacy XMPP deployments with a modern, self‑hosted solution that integrates natively into corporate LDAP and Single Sign‑On workflows.
• Mobile & Web Apps: Build cross‑platform chat clients (React, Flutter) using the provided SDKs; SAMA