💡 Architecture: How cella Talks to LXD & Docker

An overview of cella's internal architecture and how it communicates with container runtimes.

Overview

cella is a single Go binary built on the Bubbletea framework (Elm architecture for terminals). It communicates with LXD and Docker through their respective Unix domain sockets — no daemon, no config files, no external dependencies.

┌─────────────────────────────────────────────────┐
│                  cella TUI                       │
│  ┌──────────┐  ┌──────────┐  ┌───────────────┐  │
│  │ Bubbletea│  │ Lipgloss │  │ cobra CLI     │  │
│  │ (runtime)│  │ (styling)│  │ (entry point) │  │
│  └────┬─────┘  └──────────┘  └───────────────┘  │
│       │                                          │
│  ┌────┴──────────────────────────────────────┐   │
│  │        Runtime Interface (runtime.go)     │   │
│  │    ListContainers() / Exec() / Stats()    │   │
│  └────┬──────────────────────┬───────────────┘   │
│       │                      │                   │
│  ┌────┴────────┐  ┌─────────┴──────────┐        │
│  │ LXD Client  │  │ Docker Client      │        │
│  │ (unix sock) │  │ (unix sock)        │        │
│  └─────────────┘  └────────────────────┘        │
└─────────────────────────────────────────────────┘

LXD Communication

cella talks to LXD via its REST API over the Unix socket at /var/snap/lxd/common/lxd/unix.socket (snap) or /var/lib/lxd/unix.socket (deb).

• Container list — GET /1.0/containers?recursion=2
• Metrics — cgroup v2 files read directly from /sys/fs/cgroup (cpu.stat, memory.current, etc.)
• Events — GET /1.0/events (WebSocket-upgraded SSE stream)
• Exec — POST /1.0/containers/{name}/exec with WebSocket for stdin/stdout
• Config — PATCH /1.0/containers/{name} for live config changes

Docker Communication

Docker uses the same interface but talks to /var/run/docker.sock:

• Container list — GET /containers/json
• Stats — GET /containers/{id}/stats?stream=false
• Exec — POST /containers/{id}/exec + POST /exec/{id}/start
• Logs — GET /containers/{id}/logs?follow=true

Parallel Fetching

cella fetches from both runtimes concurrently using goroutines. The results are merged into a unified container list with a Runtime field ("lxd" or "docker") to distinguish them.

The Bubbletea Model

The entire TUI state lives in a single app struct (~300 fields). Bubbletea's update loop processes keyboard events and timer ticks, returning commands that trigger async operations (API calls, bpftrace output parsing, etc.).

All rendering happens in the View() method, which builds the entire screen as a string on every frame. Lipgloss handles styling, borders, and layout.