podman-mvp/ARCHITECTURE.md

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:

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