Architecture

Overview

Companion Home is built as a modern, modular self-hosting platform with several interconnected components.

Core Components

Hub (Local Server)

The Hub is the main application running on your server:

Backend: NestJS with TypeScript
Database: PostgreSQL with Drizzle ORM
Frontend: React-based dashboard
Message Queue: RabbitMQ for async task processing
Reverse Proxy: Traefik for routing and SSL

Portal

The cloud management platform at portal.ci.computer that provides:

Remote Hub management
Device pairing
Managed Cloudflare Gateway provisioning
Remote App Store access

Cloudflare Gateway

A managed Cloudflare Tunnel that securely exposes your apps without port forwarding. Provisioned and managed through Companion Portal.

Docker Layer

All apps run as Docker Compose projects. Each app is isolated in its own compose stack but shares a common Docker network for inter-app communication.

Docker Services

The Hub runs several containers defined in the production compose file:

Service	Container	Purpose
`ci-hub-db`	PostgreSQL 14	Database (port 6543)
`ci-os-hub-queue`	RabbitMQ 4	Message broker
`ci-os-hub`	Hub backend + frontend	Main application
`traefik`	Traefik v3	Reverse proxy, SSL, routing
`cloudflared`	Cloudflare tunnel agent	Managed gateway (optional)

Technologies

Docker — Containerisation
Traefik — Reverse proxy and load balancer
TypeScript — End-to-end type safety
NestJS — Backend framework
Drizzle ORM — Type-safe database access
PostgreSQL — Database
RabbitMQ — Message broker
Tailscale — Optional private networking