kodi
83 lines
3.0 KiB
Markdown
83 lines
3.0 KiB
Markdown
# 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
|