Zusam

Zusam is a lightweight, self‑hosted social platform tailored for private groups. At its core, it exposes a RESTful API written in PHP (Symfony) and serves a single‑page web application built with Preact. The architecture is intentionally minimalistic: the backend persists data in SQLite, while the frontend communicates over HTTP/JSON. This design keeps the server footprint low and simplifies deployment in constrained environments such as home servers or small VPS instances.

Technical Stack

• Backend: Symfony 6+ (PHP 8.1+) – leverages Doctrine ORM for SQLite, and the Symfony HTTP client for external link previews.
• Database: SQLite – chosen for zero‑configuration persistence, ideal for small to medium user bases.
• Frontend: Preact (React‑like API) bundled with ParcelJS – results in a fast, bundle‑size‑friendly SPA that works on older browsers (Firefox ESR, Chrome +1 year).
• Media handling: Requires Ffmpeg 3+ for video processing and Imagick for image manipulation; all media is stored on the filesystem with database paths.

Core Capabilities

• REST API: CRUD operations for users, threads, posts, media, and public links. Endpoints are versioned (/api/v1/...) to support future backward‑compatible changes.
• Link Preview: Server fetches OpenGraph/OG+ metadata from URLs, parses embedded media (YouTube, Vimeo, Imgur, SoundCloud, Twitch, Bandcamp), and returns JSON representations.
• Media Upload: Handles multipart uploads for images/videos, generates thumbnails (via Imagick) and transcoded clips (via Ffmpeg). Supports public link generation for sharing outside the group.
• Photo Albums: Grouped media collections with ordering and privacy flags, exposed through dedicated API endpoints.
• Webhooks & Plugins: While not fully fleshed out yet, the architecture exposes hook points for extensions (e.g., custom authentication backends, analytics). Future releases plan a plugin system to allow developers to add new endpoints or modify existing ones without touching core code.

Deployment & Infrastructure

• Containerization: A Docker image is available (see documentation/docker.md). The container runs the Symfony server and serves static assets, making CI/CD pipelines straightforward.
• Scalability: SQLite limits horizontal scaling; for larger deployments, developers can swap the ORM to PostgreSQL or MySQL by adjusting Doctrine mappings. The stateless REST API allows easy scaling behind a reverse proxy or load balancer.
• Self‑Hosting Requirements: PHP 8.1+ with extensions (iconv, mbstring, curl, xml, sqlite3, imagick) and Ffmpeg 3+. The webapp is static after build, so it can be served by any HTTP server (nginx, Apache, Caddy).

Integration & Extensibility

• API First: The REST API can be consumed by any client (mobile, desktop, custom web). Swagger/OpenAPI documentation is autogenerated via Symfony’s NelmioApiDocBundle.
• Webhooks: Developers can register webhook URLs to be notified of events (new post, media upload). This enables integration with external services like Slack or custom dashboards.
• Custom Themes: The Preact frontend is modular; developers can fork the repo, modify components, or inject custom CSS/JS without affecting the backend.
• Localization: Translations are managed through Weblate, making it trivial to add new languages or contribute translations.

Developer Experience

• Documentation: The repo contains comprehensive guides for Debian, Apache/nginx, and Docker setups. API docs are auto‑generated.
• Community & Licensing: AGPLv3 ensures that any derivative work remains open. The active issue tracker and pull‑request workflow encourage contributions.
• Extensibility: Symfony’s service container and event dispatcher allow deep customization without modifying core code. The lightweight stack means developers can run local instances quickly for testing.

Use Cases

• Private Group Forums: Small clubs, hobby groups, or family communities wanting a self‑hosted alternative to public social networks.
• Internal Team Communication: Companies or open‑source projects needing a lightweight, privacy‑focused forum for discussions and media sharing.
• Learning Projects: Developers looking to study a real‑world Symfony application, experiment with REST APIs, or build custom clients.

Advantages

For developers seeking a fully self‑hosted, API‑driven social platform that is easy to deploy and extend, Zusam offers a clean, modern stack with strong community backing.