admin
21d0e7cf4c
New documentation/controller/ subtree (module map + deploy/stack-lifecycle, backup, storage/monitoring/metrics, auth/hub/sync/integrations) grounded in current source; top-level documentation/README.md index across controller/agent/platform/hub/audits; REORG-NOTES with the verification ledger + flagged doc-gaps. Supersedes (keeps) the v0.33 controller planning map. Additive only. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
45 lines
2.7 KiB
Markdown
45 lines
2.7 KiB
Markdown
# Felhom — Documentation
|
||
|
||
Felhom is a managed home-server service for Hungarian households, built on a **three-component model**
|
||
over Proxmox:
|
||
|
||
- **Hub** — operator backend on k3s (`hub.felhom.eu`). Repo: `felhom.eu/hub/`.
|
||
- **Host agent** — one per Proxmox host; operator-tier; owns all Proxmox interaction. Repo: `felhom-agent/`.
|
||
- **In-guest controller** — one per customer LXC; Docker-only; manages the customer's apps. Repo: `felhom-controller/`.
|
||
|
||
This directory is the central, code-verified documentation home for all three components plus the
|
||
platform and the security-audit record.
|
||
|
||
## Sections
|
||
|
||
### Controller (in-guest) — `controller/`
|
||
The Docker-only app-domain controller. Full per-area docs grounded in current source (v0.59.0).
|
||
→ [`controller/README.md`](controller/README.md): module map, deploy & stack lifecycle, backup
|
||
architecture, storage/monitoring/metrics, auth/hub/sync/integrations.
|
||
|
||
### Host agent & platform — `architecture/`, `proxmox-platform.md`
|
||
The operator-tier agent and the Proxmox platform.
|
||
- [`architecture/01-topology-and-trust.md`](architecture/01-topology-and-trust.md) — topology & trust model
|
||
- [`architecture/03-host-agent.md`](architecture/03-host-agent.md) — the host agent (Go; v0.29.1)
|
||
- [`architecture/04-control-plane-authorization.md`](architecture/04-control-plane-authorization.md) — signing, escrow, authz
|
||
- [`architecture/02-controller-module-map.md`](architecture/02-controller-module-map.md) — **historical** v0.33 planning map; the live map is [`controller/module-map.md`](controller/module-map.md)
|
||
- [`proxmox-platform.md`](proxmox-platform.md) — Proxmox platform reference
|
||
|
||
### Hub (operator backend) — `architecture/05`
|
||
- [`architecture/05-hub-architecture.md`](architecture/05-hub-architecture.md) — hub architecture (v0.11.0)
|
||
|
||
### Security audits & remediation — `audits/`
|
||
- [`audits/deep-sweep-2026-06-13.md`](audits/deep-sweep-2026-06-13.md) — cross-repo deep audit (controller + agent) with remediation status
|
||
- [`audits/bughunt-reconcile-2026-06-13.md`](audits/bughunt-reconcile-2026-06-13.md) — reconciliation of the v0.30.3 BUGHUNT against current code + merged fix list
|
||
|
||
### Spike & test findings — `tests/`
|
||
Per-slice spike/validation findings (phases 0–5, slices 7–10). See [`tests/`](tests/).
|
||
|
||
## Conventions
|
||
|
||
- **Code-verified, not memory-derived.** Architectural claims here are checked against the actual
|
||
current source; if a claim can't be verified it is omitted and flagged, not guessed.
|
||
- Per-repo operational working files (`CLAUDE.md`, `CONTEXT.md`, `CHANGELOG.md`, `BUGHUNT.md`,
|
||
`REPORT.md`, `TASK.md`) live in their own repos — they are operational, not published docs.
|
||
- Authoritative versions at last refresh: controller **v0.59.0**, agent **v0.29.1**, hub **v0.11.0**.
|