# 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
   - `control/app_volumes.py` — volumes endpoints (list/create/delete/prune/exists)

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 control/app_volumes.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/volumes >/dev/null && echo OK
curl -fsS http://127.0.0.1:8081/api/networks/meta | jq