kodi
3.4 KiB
AGENTS.md — podman-mvp (WebUI + API)
Goal
Primary goal: extend functionality and evolve the platform.
Feature development is the default workflow.
Refactoring is allowed when:
- it improves maintainability, OR
- it is required to implement a feature.
Refactoring must always:
- be proposed first,
- remain backward compatible,
- not change existing behaviour or API contracts without agreement.
Repository structure
Backend (FastAPI)
- control/app.py (main API)
- control/app_images.py
WebUI (static Apache)
- webui/html/index.html
- webui/html/assets/js/tabs/
- webui/conf/httpd.conf
Runtime architecture (IMPORTANT)
Application runs inside a Podman pod.
Pod created with:
podman pod create
--name mvp-pod
-p 8080:8000
-p 8081:8081
--userns=keep-id
Backend container
Runs FastAPI control API with Podman access.
Created with:
podman run -d --pod mvp-pod
--name mvp-backend
--ipc=host
--pid=host
-e XDG_RUNTIME_DIR=/run/user/1000
-e DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/1000/bus
-v /run/user/1000:/run/user/1000:rw
-v /run/user/1000/podman/podman.sock:/run/user/1000/podman/podman.sock:rw
-v /home/kodi/.config/containers:/app/workloads:rw
mvp-control:latest
Important notes:
- Backend communicates with Podman through unix socket.
- User-session Podman is used (not root).
- DBus access is required.
- Host PID/IPC namespaces are intentional.
Do NOT change these assumptions without proposal.
WebUI container
Static Apache frontend.
podman run -d --pod mvp-pod
--name mvp-webui
-v $HOME/.config/podman-mvp/webui/html:/usr/local/apache2/htdocs:ro
-v $HOME/.config/podman-mvp/webui/conf/httpd.conf:/usr/local/apache2/conf/httpd.conf:ro
docker.io/library/httpd:2.4
Frontend is static JS calling API through proxy.
Access
WebUI: http://127.0.0.1:8081/
API (via proxy): http://127.0.0.1:8081/api/
Testing workflow (REQUIRED)
Always validate changes using curl.
Example:
curl -s http://127.0.0.1:8081/api/...
Before proposing implementation:
- Analyse existing endpoints.
- Confirm available data using curl tests.
- Propose minimal change.
- Provide verification curl commands.
Contract rules (HARD)
- Never break existing API responses.
- Never rename or remove JSON keys.
- Maintain backward compatibility.
New functionality must be added via:
- new endpoints, OR
- optional response fields.
Security rules:
- No shell=True
- subprocess must be explicit and safe
- Respect allowed_units.txt
- Never assume systemd states.
Change policy
Preferred workflow:
- Analyse existing behaviour.
- Propose small implementation plan.
- Identify affected files.
- Provide curl validation tests.
- Implement after agreement.
Avoid:
- large rewrites
- structural changes without need
- hidden refactors. All significant changes must follow PR_RULES.md workflow.
UI direction
Target style: Portainer-like dashboard UI.
Guidelines:
- tables and overview panels
- container status badges
- row-level actions
- minimalistic professional layout
Do NOT introduce large frontend frameworks without agreement.
Coding style
Follow existing structure and conventions of each file.
Do not reformat unrelated code.
Minimize diff size whenever possible.
Safety boundaries
Follow SAFE_FILES.md before modifying infrastructure or core files.