Databag

Databag is a lightweight, federated messenger designed for self‑hosting environments. At its core it implements a topic‑based communication model rather than traditional one‑to‑one contact lists, enabling unlimited participants per thread while keeping the server footprint minimal enough to run on a Raspberry Pi Zero. The application exposes a RESTful API and WebSocket endpoints for real‑time messaging, authentication, and call signalling. End‑to‑end encryption is enforced at the application layer using asymmetric key pairs that are not tied to any blockchain or domain, ensuring that even a privileged administrator cannot read sealed topics.

Key Features

• Decentralized & Federated – Nodes communicate directly over HTTPS/WebSocket; users on separate instances can chat without a central broker.
• Public‑Private Key Identity – Users generate key pairs locally; the server stores only a public identifier, preserving privacy.
• End‑to‑End Encryption – All payloads are encrypted client‑side; the server only relays ciphertext.
• Audio/Video Calls – Signalling via WebSocket; NAT traversal requires an external TURN/STUN relay (not bundled).
• Topic‑Based Threads – Messages are grouped by topic; threads can have unlimited members.
• Low Latency Push – WebSocket push events replace polling, enabling near real‑time notifications.
• Multi‑Factor Authentication – TOTP integration for added account security.

Technical Stack

The server binary is statically compiled, allowing it to run on any Linux distribution without external dependencies. The minimal footprint and use of WebSockets make the application suitable for edge deployments.

Core Capabilities & APIs

• Authentication – JWT‑based session tokens; TOTP support via /api/auth/totp.
• User Management – CRUD endpoints for user profiles and key rotation.
• Topic APIs – Create, delete, invite participants; /api/topics/{id}/messages supports pagination and read receipts.
• Messaging – POST /api/messages with signed payload; WebSocket channel ws://<node>/ws for real‑time delivery.
• Call Signalling – WebSocket messages call-init, call-answer, ice-candidate for WebRTC.
• Webhooks – Optional outbound hooks for new messages or calls, configurable per topic.

All APIs are documented in OpenAPI format and available under /api/docs. The client SDKs consume these endpoints directly, providing a consistent developer experience.

Deployment & Infrastructure

Databag is intentionally minimalistic: a single Go binary, a PostgreSQL instance, and an optional TURN server for calls. It can be run:

• On bare metal – as a systemd service or Docker container.
• In containers – prebuilt images support both amd64 and arm64.
• With Docker‑Compose – the provided compose.yaml or docker-compose-swag.yml includes NGINX reverse proxy and automatic Let’s Encrypt certificates.
• Scalable – multiple instances can be load‑balanced; the database is the single point of coordination, but reads can be sharded if needed.

Because the server stores only public keys and encrypted payloads, a compromised node does not expose user data. The lightweight design also allows scaling to thousands of concurrent WebSocket connections on modest hardware.

Integration & Extensibility

• Plugin System – The core exposes a Go plugin interface; third‑party modules can add new message types, custom authentication backends, or analytics.
• Webhooks & Callbacks – External services can subscribe to topic events via HTTPS callbacks.
• API Hooks – Custom middleware can be injected into the HTTP stack for rate‑limiting, logging, or feature toggles.
• Cross‑Platform Clients – The web client is open source; developers can fork or embed it in other applications.
• Federation Protocol – The node communicates with peers using a JSON‑over‑HTTPS spec; developers can implement new federation nodes in any language that supports the same API surface.

Developer Experience

• Configuration – Environment variables (DB_URL, DOMAIN, TURN_*) control all aspects; no hard‑coded defaults.
• Documentation – The doc/ folder contains a design overview, API spec, and Figma UI files.
• Community – Active GitHub issues, Slack channel, and a Figma file for UI feedback.
• Testing – The repository includes unit tests and integration scripts; CI runs on GitHub Actions.

The developer workflow is straightforward: pull the repo, run docker-compose up, and start hacking on the Go