Tech stack
Layer 2. Core. Core
Overview
Section titled “Overview”SHC is a Go CLI and a daemon. A deployment is the running unit.
The CLI (shc) and the daemon (shcd)
are two binaries built from cmd/shc/ and cmd/shcd/; the rest of the
code is top-level; there is no internal/ directory, and the same
layer names (core/, daemon/, modules/, subsystems/) exist in
both repos. The open core lives in
ce, consumed here as a
pinned Go module; this repo holds the enterprise half of each layer.
Paths below are written ce <path> or shc <path> wherever it matters.
This document defines the technical choices for all aspects of the
codebase.
Core Stack
Section titled “Core Stack”Language & Runtime
Section titled “Language & Runtime”| Component | Choice | Notes |
|---|---|---|
| Language | Go 1.25+ | Compiled binaries, pure Go (CGO_ENABLED=0) |
| Build toolchain | asdf + go | make build produces bin/shc + bin/shcd |
| Bundled binaries | rqlited | Fetched to vendor/rqlite/ by make vendor/rqlite |
CLI Framework
Section titled “CLI Framework”| Component | Choice | Notes |
|---|---|---|
| CLI Framework | spf13/cobra | Standard Go command tree |
| Terminal Output | charmbracelet/lipgloss + bubbletea | Styled text + Bubbletea TUI for shc hud |
| Shell Completion | cobra-generated | Bash/Zsh/Fish completion support |
API Layer
Section titled “API Layer”| Component | Choice | Notes |
|---|---|---|
| HTTP Router | go-chi | Lightweight chi router + middleware |
| HTTP Server | net/http with chi | UDS + TCP listeners served from one daemon |
| Validation | go-playground/validator/v10 | validate: struct tags + custom validators |
Server Architecture
Section titled “Server Architecture”| Component | Choice | Notes |
|---|---|---|
| Lifecycle Manager | ce subsystems/lifecycle | Central orchestrator for all server subsystems |
| Subsystem Protocol | lifecycle.Subsystem | Uniform interface: Name(), Start(), Stop(), Health() |
| Fail-Fast | systemd | Service crashes bring down server; systemd restarts |
| Leader Election | raft (leader_hub) | The raft leader id (rqlited) drives the leader signal |
See daemon-manager for details.
Database
Section titled “Database”| Component | Choice | Notes |
|---|---|---|
| Database | SQLite / rqlite | Plain file + WAL at {state}/shc.db single-node; raft-replicated rqlite in clusters |
| Driver | modernc.org/sqlite (pure Go) | Registered as the sqlite sql driver; the pool swaps to shc-rqlite at boot when {state}/engine.json exists |
| Distributed | rqlite (external rqlited process) | Supervised by the daemon (shc core/rqlited); SQLite with Raft consensus |
| Query layer | ent ORM + per-module repos | ent-generated client (ce ent/) over the shared db pool; one *StackRepo / *NodeRepo per module wraps it |
| Migrations | Atlas (ariga/atlas) | One first file under ce migrations/, then migrations appended with make migrate NAME=<slug>; integrity hash in atlas.sum, released lines held in core/db/released.sum |
ent/ and migrations/ live in the ce repo, not here; make migrate in this repo is a signpost that prints where they went and
exits non-zero. The daemon still applies the migration at startup from
the embedded SQL, so there is nothing to run on this side.
Database modes:
- Single-node: plain SQLite (no raft, zero coordination)
- Cluster: external rqlited raft engine (automatic promotion when the first
shc node joinenrolls)
Container Orchestration
Section titled “Container Orchestration”| Component | Choice | Notes |
|---|---|---|
| Node runtime | docker, podman, incus, apple | One runtime per node |
| Runtime execution | Compose CLI, incus-compose or Apple’s container CLI | All four executors linked into shcd |
| Cluster state | rqlited | Raft on mesh0 |
| Container fabric | shc0 | WireGuard and nftables on Linux |
Sources: CE daemon/imports.go, core/hostplat and modules/fabric.
See Runtime support.
Code Organization
Section titled “Code Organization”Project Structure
Section titled “Project Structure”The ce repo carries the open core: the registries, the base modules, the schema:
ce/├── cmd/{shc,shcd}/ # the reference mains├── core/ # cross-module primitives│ ├── coded/ # X######CCCCCC error machinery│ ├── api/ # chi helpers, manifest, auth, SSE│ ├── db/ # *db.Pool, migration runner, scan helpers│ ├── log/ # typed slog wrapper + audit│ ├── paths/ # XDG-aware filesystem layout│ ├── registry/ # central router + command + error + cron registries│ └── ... # ~35 packages in all├── daemon/ # daemon boot + composition root├── modules/ # base feature modules (one per domain)│ ├── app/ backup/ vault/ config/ logs/ shell/ …│ └── {module}/commands/ # that module's cobra subcommands├── subsystems/│ ├── lifecycle/ # supervisor + resolver│ └── impl/ # config loader, event bus, queue, cron runner,│ # http + internal-API listeners, reconcilers, ...├── ent/ # ent schema + generated client└── migrations/ # Atlas SQL migrations + atlas.sumThis repo pins that module and adds the enterprise half of the same layers, plus the out-of-process components:
shc/├── cmd/│ ├── shc/ # CLI binary (cobra root)│ ├── shcd/ # daemon binary│ └── shc-x9s/ validate-templates/ verify-image-pins/ verify-addon-freshness/├── cli/ # CLI composition: build shape, license + quota clients├── core/ # db, rqlited supervisor, otel boot, collector config, ...├── daemon/wiring/ # the wiring this repo contributes to the composition root├── modules/ # cluster, license, quota, node, tenant, user, hud, ...├── subsystems/ # rqlite engine, leader elector, collectors (flat, no impl/)├── pkg/ # apiclient, appimages, scrub├── apps/ # app catalog; fixtures/ standalone/ enterprise/ bucket the rest├── collector/ forward-auth/ traefik/ keycloak/ license-broker/ # out-of-process components├── terraform/ # provider + modules + examples├── website/ # Astro + Starlight docs and marketing site├── tests/ # own Go module: unit/, integration/, parity/, e2e/, proxmox/└── docs/ # Documentationcollector/processor/*, forward-auth/, traefik/plugin/,
traefik/render/, terraform/provider/ and tests/ are each their own
Go module.
Module Pattern
Section titled “Module Pattern”Both repos’ modules/{module}/ directories follow the same structure, so
a module reads the same whether it is a base module in ce or an
enterprise module here:
modules/{module}/├── service.go # *Service struct + methods (business logic)├── router.go # HTTP routes via chi├── types.go # request/response Go structs + validate tags├── errors.go # X######CCCCCC factories + Spec slice + init()├── events.go # event handler registrations (where applicable)├── register.go # init() side-effects (router builder, command builder, runtime singleton)├── service_test.go # unit tests against fakes├── router_test.go└── commands/ # cobra subcommand surface (if module exposes CLI verbs) ├── main.go └── ...Development Tools
Section titled “Development Tools”Code Quality
Section titled “Code Quality”| Tool | Purpose | Config |
|---|---|---|
| gofmt | Code formatting | (canonical) |
| golangci-lint | Lint suite (forbidigo, gocritic, staticcheck, errcheck, …) | .golangci.yml |
| shfmt | Shell-script formatting (apps, tests) | make format |
Lint configuration highlights
Section titled “Lint configuration highlights”forbidigorejectserrors.Newandfmt.Errorfoutside test files: every error path must surface a*coded.CodedError.staticcheck,errcheck,unused,gocritic,goimportsall on.- Tests are exempt from forbidigo’s stricter rules but not from
gofmt/unused/staticcheck.
Testing
Section titled “Testing”Unit Tests (go test)
Section titled “Unit Tests (go test)”| Tool | Purpose |
|---|---|
testing stdlib | Test runner |
testing.TB.Context | Per-test cancellable context |
httptest | In-process HTTP server for handler tests |
| Hand-rolled fakes | Cross-module seam stand-ins |
# Run all testsmake test/unit
# Run with coveragego test -coverprofile=coverage.out ./...go tool cover -html=coverage.out -o coverage.html
# Run in parallel (default: GOMAXPROCS); disable with -p=1go test -p=1 ./...
# Race detector (integration suite turns this on by default)go test -race ./...E2E Tests (Bats)
Section titled “E2E Tests (Bats)”| Tool | Purpose |
|---|---|
| Bats | Bash Automated Testing System |
| Proxmox | Multi-node VM e2e |
Observability
Section titled “Observability”| Surface | Component |
|---|---|
| Logs | typed wrapper in core/log/; WARN+ requires a *coded.CodedError (raw slog.Warn/slog.Error are lint-banned); structured JSON + audit class + event-bus fan-out |
| Metrics | OpenTelemetry meters + scoped registries (modules/metrics/) |
| Tracing | OpenTelemetry traces with W3C traceparent propagation |
| Events | Internal event bus (modules/events/) + SSE for clients |
// modules/metrics/definitions.go: sample shapesbackupTotal := svc.RecordCounter(ctx, "shc_backup_total", 1)activeStacks := svc.RecordGauge(ctx, "shc_active_stacks", float64(n))opDuration := svc.RecordHistogram(ctx, "shc_operation_duration_seconds", elapsed.Seconds())Dependencies
Section titled “Dependencies”Runtime dependencies (selected, see go.mod for the full list):
modernc.org/sqlite // pure-Go sqlite drivergithub.com/spf13/cobra // CLI frameworkgithub.com/go-chi/chi/v5 // HTTP routergithub.com/go-playground/validator/v10 // input validationgo.opentelemetry.io/otel // metrics + tracinggithub.com/charmbracelet/bubbletea // HUD TUIgithub.com/charmbracelet/lipgloss // terminal stylingariga.io/atlas // migrationsgithub.com/moby/docker // docker SDKgo.yaml.in/yaml/v3 // YAML parsingDev tooling lives in go.mod build constraints; gofmt,
golangci-lint, and bats are installed via asdf at make prepare.
Packaging & distribution
Section titled “Packaging & distribution”Installation methods
Section titled “Installation methods”| Method | Command | Use case |
|---|---|---|
.deb/.rpm/.apk | make package && sudo {dpkg,rpm,apk} -i dist/shc_*_linux_amd64.<fmt> | Production |
| Direct Install | make install | Development/testing |
Package structure (built by goreleaser/nfpm)
Section titled “Package structure (built by goreleaser/nfpm)”| Component | Path / approach |
|---|---|
| Build System | GoReleaser + nfpm (.goreleaser.yaml) |
| Go binaries | /usr/bin/shc, /usr/bin/shcd (static, CGO_ENABLED=0) |
| Bundled rqlited | /usr/lib/shc/bin/rqlited (spawned by the daemon in cluster mode) |
| systemd unit | /usr/lib/systemd/system/shc.service (static, FHS paths) |
| Group/Dirs | systemd-sysusers (shc.sysusers.conf), systemd-tmpfiles (shc.tmpfiles.conf) |
| Scriptlets | scripts/{postinstall,preremove,postremove}.sh |
NOT in tech stack
Section titled “NOT in tech stack”These technologies are explicitly not used:
| Technology | Reason |
|---|---|
| Vue/Svelte | React is the one UI framework in the tree: see below |
| Tailwind | The CSS that exists is hand-written; no utility framework |
| PostgreSQL/MySQL | SQLite/rqlite is sufficient |
| Redis | Not needed for current scope |
| Kubernetes | One runtime per node: docker, podman, incus, apple |
| GraphQL | REST API is simpler |
| Generated mocks | Hand-rolled fakes are cheaper to maintain |
The control plane is Go; the tree is not
Section titled “The control plane is Go; the tree is not”The control plane is Go. The repo also carries frontend code and components in other languages:
| Surface | What it is |
|---|---|
apps/console/ | The SHC web console, a multiplatform.one app (React + Tamagui), shipping web, iOS, Android and GTK4 from one codebase |
apps/marketplace/ | The app-store front end, same stack |
website/ | Astro 7 + Starlight documentation and marketing site: .astro, TypeScript, .mjs build scripts, hand-written CSS, a pnpm workspace, Playwright |
traefik/plugin/ | Yaegi-interpreted Traefik middleware that injects an app-launcher menu: it writes an inline <style> block and an inline <script> into HTML responses (menu.go) |
keycloak/ | A Keycloak SPI in Java (Maven), plus the shc admin theme: keycloak/themes/shc/admin/resources/css/shc-admin.css |
apps/*/ | Apps carry whatever their upstream needs (e.g. apps/security/ivatar/login.html) |
The frontends are named in FRONTEND_APPS in the Makefile and are not
catalogue apps: see app buckets.
Why a console does not cost the CLI-first principle
Section titled “Why a console does not cost the CLI-first principle”The console is a client of the same API the CLI calls. It has no
private endpoint, no back door into the daemon, and no capability the
command line lacks: both speak /api/method/shc.* and
/api/resource/<DocType> over the same auth. Adding a screen cannot add
a feature; the RPC has to exist first, which means it is scriptable
before it is clickable.
That ordering is the whole guarantee, and it is why the console is a addition rather than a reversal. The failure mode to watch for is the opposite order: a capability that reaches the console without an RPC behind it. If you ever find one, the defect is the missing RPC.
React is here because the console consumes multiplatform.one, which targets web, iOS, Android, GTK4 and VS Code from one component tree. That is the reason it earns its place: five surfaces, one codebase, not because a web page needed a framework.