# Felhom Controller — Documentation

The **in-guest controller** (`felhom-controller`): one per customer LXC, Docker-only, Hungarian web
dashboard. It manages the customer's app stacks and app-data backups, reports to the hub, and delegates
all Proxmox/disk operations to the host agent. Current version **v0.59.0**.

These docs are **code-verified against current source** (`felhom-controller/controller/internal/`) and
are the authoritative architecture reference. The repo-local `controller/README.md` is a build/dev
quickstart that points here; operational working files (`CLAUDE.md`, `CONTEXT.md`, `CHANGELOG.md`,
`BUGHUNT.md`) stay in the controller repo.

## Index

- [module-map.md](module-map.md) — per-package map of the current controller (supersedes the v0.33
  planning map in `../architecture/02-controller-module-map.md`).
- [deploy-and-stack-lifecycle.md](deploy-and-stack-lifecycle.md) — stack model, the deploy flow
  (incl. the v0.59 crash-safe `deployed` persistence + fail-closed secret encryption), protected
  stacks, base-infra bring-up (`EnsureBaseStack`).
- [backup-architecture.md](backup-architecture.md) — app-data backup: DB dumps, per-app recovery
  units, restore + the fail-closed data-key gate, Tier-2 off-drive copies, and the controller↔agent/PBS
  split for whole-guest backup.
- [storage-monitoring-metrics.md](storage-monitoring-metrics.md) — storage registry, disk topology &
  operations delegated to the agent, the v0.58 Docker-data headroom prevention layer, host metrics,
  the SQLite metrics store, and health monitoring.
- [auth-hub-sync-integrations.md](auth-hub-sync-integrations.md) — auth/CSRF/sessions, the pre-auth
  setup wizard + bootstrap ingestion, hub reporting & notifications, catalog sync, app-to-app
  integrations, geo-restriction, self-update, and asset sync.

## Cross-references

- Host agent architecture: [`../architecture/03-host-agent.md`](../architecture/03-host-agent.md)
- Control-plane authorization (signing/escrow): [`../architecture/04-control-plane-authorization.md`](../architecture/04-control-plane-authorization.md)
- Hub: [`../architecture/05-hub-architecture.md`](../architecture/05-hub-architecture.md)
- Topology & trust: [`../architecture/01-topology-and-trust.md`](../architecture/01-topology-and-trust.md)
- Security audits & remediation: [`../audits/`](../audits/)