enuxia-frappe-aio/docs/ARCHITECTURE.md

Architecture

Overview

Browser
  |
  v
Controller
  |
  | typed JSON / Unix socket 0600
  v
Agent
  |\
  | \__ SQLite operation state
  |
  \____ Docker API
          |
          +-- Frappe Compose services
          +-- temporary operation containers

Controller

The controller displays agent health, service state, logs, backup history, and operation results. It has no Docker access and no direct SQLite access.

Agent

The agent validates typed requests, owns Docker access, discovers resources through Compose labels, persists operations, runs the worker, and returns bounded structured responses.

Worker

The worker atomically claims queued operations, marks them running, executes an allow-listed operation, and persists a result or error. Interrupted running operations are marked failed after restart.

Backup workflow

Controller -> StartOperation(Backup)
Agent -> persist queued operation
Worker -> discover runtime -> run backup -> hash artifacts -> persist BackupResult
Controller -> poll status -> display result and history

Verification workflow

Controller -> StartOperation(VerifyBackup)
Agent -> load persisted manifest
Worker -> mount storage read-only -> recompute sizes and SHA-256 -> persist result
Controller -> display global and per-artifact result

Discovery contract

The implementation relies on Docker Compose labels such as com.docker.compose.project, com.docker.compose.service, and com.docker.compose.volume.

Physical container names are display information, not stable identifiers.