refractor: afgerond

2026-02-28 15:51:58 +01:00
parent df2a577402
commit 7d84733b17
4 changed files with 135 additions and 5 deletions
@@ -0,0 +1,82 @@
+# ARCHITECTURE.md — podman-mvp (WebUI + API)
+
+## Purpose
+This document describes **where code lives** and **which module owns what**.
+It is a factual map of the system for reviewers and agents.
+
+## Runtime + Test Base URLs
+
+### WebUI
+- http://127.0.0.1:8081/
+
+### API (via WebUI reverse proxy)
+- Base URL: http://127.0.0.1:8081/api
+
+**All verification commands must target `127.0.0.1:8081` unless explicitly stated otherwise.**
+
+Example:
+- `curl -fsS http://127.0.0.1:8081/api/health`
+
+## Architecture Overview (Modular Monolith)
+Single deployable backend service, split into modules (routers) by domain.
+
+### Layers
+1. **Bootstrap / Composition Root**
+   - `control/app.py`
+   - Responsibilities:
+     - create FastAPI app
+     - include routers
+     - register startup events (if needed)
+   - Hard rule: **no feature endpoints** and **no system logic** here.
+
+2. **System / Platform Router**
+   - `control/app_system.py`
+   - Owns platform endpoints such as:
+     - `/health`
+     - `/daemon-reload`
+     - systemctl endpoints (`/{action}/{unit}`, legacy `/api/<action>/<unit>`)
+     - diagnostic endpoints (e.g. `/test-hybrid`, if present)
+   - Route ordering rule: broad patterns like `/{action}/{unit}` must be defined **last**.
+
+3. **Feature Routers (UI Tabs / Domains)**
+   - `control/app_containers.py` — containers tab endpoints (dashboard, inspect, logs, stats stream)
+   - `control/app_pods.py` — pods tab endpoints (dashboard, pod actions)
+   - `control/app_networks.py` — networks tab endpoints
+   - `control/app_files.py` — files/workloads endpoints (tree/read/save/etc.)
+   - `control/app_images.py` — images endpoints
+
+4. **Shared Infrastructure Layer**
+   - `control/common.py`
+   - Owns:
+     - Podman HTTP helpers (unix-socket requests)
+     - systemctl/subprocess helpers (when shared)
+     - shared parsing/normalization utilities
+   - Hard rule: routers should not duplicate shared helpers.
+
+## Boundaries (Hard Rules)
+- `control/app.py` is **bootstrap-only**.
+- Endpoints must live in the appropriate router module:
+  - system/platform → `app_system.py`
+  - domain feature → `app_<domain>.py`
+- Shared helpers belong in `common.py` (not copied into routers).
+- Legacy `allow_list` / `allowed_units.txt` functionality is removed and must NOT be reintroduced.
+
+## Contracts
+API response shapes are governed by:
+- `contracts/API_GOLDEN.md`
+
+No endpoint response keys may be removed or renamed without explicit approval.
+
+## Required Verification (Minimal)
+After any change affecting backend routing or shared helpers, run:
+
+```bash
+python3 -m py_compile control/app.py control/common.py control/app_system.py \
+  control/app_containers.py control/app_pods.py control/app_networks.py \
+  control/app_files.py control/app_images.py
+
+curl -fsS http://127.0.0.1:8081/api/health | jq
+curl -fsS http://127.0.0.1:8081/api/pods-dashboard >/dev/null && echo OK
+curl -fsS http://127.0.0.1:8081/api/containers-dashboard >/dev/null && echo OK
+curl -fsS http://127.0.0.1:8081/api/files/tree >/dev/null && echo OK
+curl -fsS http://127.0.0.1:8081/api/networks/meta | jq