60 lines
4.6 KiB
Markdown
60 lines
4.6 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.
|
||
|
||
### Where we stand — `architecture/where-felhom-stands.*`
|
||
The operator's one-page picture of what is proven, built, partial and missing.
|
||
- [`architecture/where-felhom-stands.html`](architecture/where-felhom-stands.html) — **generated**; do not hand-edit
|
||
- [`architecture/where-felhom-stands.yaml`](architecture/where-felhom-stands.yaml) — the data behind it; every claim cites its source. Gate: `scripts/check_stands.py`; regenerate with `scripts/render_stands.py`
|
||
- [`architecture/where-felhom-stands-2026-08-09-snapshot.html`](architecture/where-felhom-stands-2026-08-09-snapshot.html) — **a dated snapshot, NOT maintained.** The original React bundle, kept for the record; its statuses are those of 2026-08-09 before the verification pass
|
||
|
||
### The whole system on one page — `architecture/felhom-system-poster.*`
|
||
A poster for the operator: every machine, path, backup tier, time and key on a single sheet.
|
||
- [`architecture/felhom-system-poster.html`](architecture/felhom-system-poster.html) — the drawing. **Made in Claude Design, NOT generated by anything in this repo**, so do not expect a renderer; it is self-contained (fonts and scripts are inlined — it opens with no network)
|
||
- [`architecture/felhom-system-poster.facts.md`](architecture/felhom-system-poster.facts.md) — **the source of every fact on it. Change the facts here first.** Rule: `.claude/rules/unprompted-work.md` §6. Gate: `scripts/poster_facts_gate.py` WARNS (never fails) when this file has a newer commit than the drawing
|
||
|
||
### 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
|
||
- [`architecture/11-os-updates.md`](architecture/11-os-updates.md) — operating-system updates: host, guest, Docker engine (**NOT RATIFIED**, 2026-10-04)
|
||
|
||
### Hub (operator backend) — `architecture/05`
|
||
- [`architecture/05-hub-architecture.md`](architecture/05-hub-architecture.md) — hub architecture (v0.11.0)
|
||
|
||
### Apps — `architecture/15`
|
||
- [`architecture/15-media-library.md`](architecture/15-media-library.md) — the media library: media apps on every drive, the links, the restart notice (**DRAFT**, 2026-10-14)
|
||
|
||
### 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**.
|