Simple Agility Back-Office Suite Architecture

Architectural Mandate: Formalized by Simple Agility Decision Log under decision SA-15 (Decided 2026-11-06 by Jake). This specification governs the extraction of shared business support services out of individual product applications into an autonomous, stack-level deployment plane located in repository /backoffice.

In the Simple Agility Stack, product platforms such as Pressroom (customer communication), Wikantik (knowledge engineering), and Stockroom (commerce inventory) operate as sovereign, decoupled systems. Prior to release 0.7.2 of Pressroom, shared business services—specifically web analytics (Umami) and newsletter distribution (Listmonk)—were bundled directly within Pressroom's local Docker Compose deployment on host docker1.

Operating shared services inside a product repository introduces tight coupling: Pressroom maintained database lifecycles, backup routines, retention scripts, and superuser database credentials for tools that multiple applications across the stack consume. Under SA-15, all shared business services migrate to a dedicated Back-Office Suite deployed to repository /backoffice.

The suite is a stack-level sibling of the observability plane (SimpleAgilityObservabilityPlane). It owns the container orchestration, isolated PostgreSQL engines, persistent volumes, backup routines, and administrative provisioning for its tenants. Applications interact with back-office services purely as client consumers over standard HTTP APIs and private network channels.

flowchart TD
    subgraph Edge_Ingress["Edge & Ingress (Host: cloudflare 192.168.5.50)"]
        CF_TUNNEL["cloudflared Tunnel"]
        PUB_ANALYTICS["analytics.wikantik.com"]
        PUB_NEWSLETTER["newsletter.wikantik.com"]
        PUB_ANALYTICS --> CF_TUNNEL
        PUB_NEWSLETTER --> CF_TUNNEL
    end

    subgraph Product_Plane["Product Workloads (Host: docker1 192.168.5.51)"]
        WIKANTIK["Wikantik (:8080)"]
        PRESSROOM["Pressroom Caddy & App (:8084)"]
        PROXY_TRACKER["Same-Origin /analytics/* Proxy"]
        PRESSROOM --> PROXY_TRACKER
    end

    subgraph Backoffice_Suite["Back-Office Suite (Host: docker2 192.168.5.52 / ~/backoffice)"]
        BO_CADDY["Back-Office Caddy Proxy (:8085)"]
        UMAMI_SVC["Umami 3.3.0 Engine (:3000)"]
        UMAMI_DB[("Umami PostgreSQL 18<br/>pressroom-umami-pgdata")]
        LISTMONK_SVC["Listmonk Engine (:9000)"]
        LISTMONK_DB[("Listmonk PostgreSQL 18<br/>pressroom-listmonk-pgdata")]
        BACKUP_CRON["backoffice-backup Cron Loop"]

        BO_CADDY --> UMAMI_SVC
        BO_CADDY --> LISTMONK_SVC
        UMAMI_SVC --- UMAMI_DB
        LISTMONK_SVC --- LISTMONK_DB
        BACKUP_CRON -.->|Nightly pg_dump| UMAMI_DB
        BACKUP_CRON -.->|Nightly pg_dump| LISTMONK_DB
    end

    subgraph Observability["Observability Plane (Host: inference 192.168.5.53)"]
        JAKEMON["jakemon Central"]
        GRAFANA["Grafana Dashboards"]
        GRAFANA -.->|Read-Only SQL via grafana_ro| UMAMI_DB
        JAKEMON -.->|Scrape /metrics & Blackbox| BO_CADDY
    end

    CF_TUNNEL -->|Admin Dashboards| BO_CADDY
    PROXY_TRACKER -->|LAN Telemetry Beacons| BO_CADDY
    WIKANTIK -.->|Future LAN Proxy| BO_CADDY

1. Fleet Placement and Ingress Topology

The back-office suite is physically deployed to docker2 (192.168.5.52, docker2.lan). Deploying to docker2 redistributes compute and memory away from docker1, which is dedicated to high-traffic production workloads for Wikantik and Pressroom.

Host Network and Ingress Routing

Following the architectural rules established in Home Lab Fleet and Ingress:

  1. Public Administration Routing: Administrative consoles for Umami and Listmonk are published externally through the centralized Cloudflare Tunnel running on host cloudflare (192.168.5.50). Public DNS routes analytics.wikantik.com and newsletter.wikantik.com terminate TLS at Cloudflare and forward plain HTTP to the back-office reverse proxy on docker2.
  2. Port Allocations: Host ports follow the \ge 8080 homelab convention. docker2 exposes:
    • Port 8085: Back-Office Caddy reverse proxy handling virtual hosts for analytics.wikantik.com and newsletter.wikantik.com.
    • Port 5434 / 5435: Optional loopback/LAN binds for database inspection if direct TCP access is required by Jakemon (otherwise accessed over Docker networks).
  3. Telemetry Beacon Routing (Same-Origin Proxying): End-user telemetry beacons emitted from browser sessions never connect directly to analytics.wikantik.com. To protect reader privacy, circumvent restrictive client adblockers, and adhere to strict Content Security Policies (CSP), client applications proxy beacons same-origin. For example, Pressroom's edge Caddy on docker1 accepts /analytics/script.js and /analytics/api/send, proxying these requests internally over the LAN to http://docker2.lan:8085.
  4. Proxy Header Trust: The Caddy reverse proxy on docker2 is configured with trusted_proxies 192.168.5.50 192.168.5.51. This ensures that X-Forwarded-For and CF-Connecting-IP headers supplied by Cloudflare and client edge proxies are preserved, enabling Umami to calculate accurate geographic and visitor telemetry without IP masking.

2. Container Architecture and Decoupled Compose Specification

The seed implementation of the suite was originally drafted in Pressroom's docker-compose.backoffice.yml. In repository /backoffice, this configuration is fully decoupled from the Pressroom application image (ghcr.io/jakefearsd/pressroom). All maintenance tasks, database setup jobs, and backup loops run on standard, digest-pinned postgres:18 and alpine images with local shell scripts mounted via Compose volumes.

Architectural Invariants

Reference docker-compose.yml

# /backoffice/docker-compose.yml
# Simple Agility Back-Office Suite: Umami & Listmonk (SA-15)

x-logging: &logging
  driver: json-file
  options:
    max-size: "10m"
    max-file: "5"

services:
  caddy:
    image: caddy:2.9-alpine
    restart: unless-stopped
    logging: *logging
    ports:
      - "8085:8085"
    volumes:
      - ./deploy/Caddyfile:/etc/caddy/Caddyfile:ro
      - caddy-data:/data
      - caddy-config:/config
    networks:
      - ingress_net

  umami:
    image: docker.umami.is/umami-software/umami@sha256:87312d334d009ee67ee0d2fba8fed01435547cc468e452243aef5133a9984d48
    restart: unless-stopped
    logging: *logging
    depends_on:
      umami-db:
        condition: service_healthy
    environment:
      DATABASE_URL: postgresql://${UMAMI_DB_USER:-umami}:${UMAMI_DB_PASSWORD:?UMAMI_DB_PASSWORD required}@umami-db:5432/${UMAMI_DB:-umami}
      DATABASE_TYPE: postgresql
      APP_SECRET: ${UMAMI_APP_SECRET:?UMAMI_APP_SECRET required}
      CLIENT_IP_HEADER: X-Forwarded-For
      DISABLE_TELEMETRY: "1"
      TRACKER_SCRIPT_NAME: script.js
    networks:
      - ingress_net
      - analytics_net

  umami-db:
    image: postgres:18@sha256:4ef4dbc939d61acea57712655ddb4b4ab27419c913f94cca0cd57cb3ea3c2280
    restart: unless-stopped
    logging: *logging
    environment:
      POSTGRES_DB: ${UMAMI_DB:-umami}
      POSTGRES_USER: ${UMAMI_DB_USER:-umami}
      POSTGRES_PASSWORD: ${UMAMI_DB_PASSWORD:?UMAMI_DB_PASSWORD required}
    volumes:
      - backoffice-umami-pgdata:/var/lib/postgresql
      - ./deploy/sql/umami-init.sql:/docker-entrypoint-initdb.d/01-init.sql:ro
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -h 127.0.0.1 -U ${UMAMI_DB_USER:-umami} -d ${UMAMI_DB:-umami}"]
      interval: 5s
      timeout: 5s
      retries: 20
    networks:
      - analytics_net

  listmonk:
    image: listmonk/listmonk:v4.1.0
    restart: unless-stopped
    logging: *logging
    depends_on:
      listmonk-db:
        condition: service_healthy
    environment:
      LISTMONK_db__host: listmonk-db
      LISTMONK_db__port: "5432"
      LISTMONK_db__user: ${LISTMONK_DB_USER:-listmonk}
      LISTMONK_db__password: ${LISTMONK_DB_PASSWORD:?LISTMONK_DB_PASSWORD required}
      LISTMONK_db__database: ${LISTMONK_DB:-listmonk}
      LISTMONK_db__ssl_mode: disable
      LISTMONK_ADMIN_USER: ${LISTMONK_ADMIN_USER:-admin}
      LISTMONK_ADMIN_PASSWORD: ${LISTMONK_ADMIN_PASSWORD:?LISTMONK_ADMIN_PASSWORD required}
    networks:
      - ingress_net
      - newsletter_net

  listmonk-db:
    image: postgres:18@sha256:4ef4dbc939d61acea57712655ddb4b4ab27419c913f94cca0cd57cb3ea3c2280
    restart: unless-stopped
    logging: *logging
    environment:
      POSTGRES_DB: ${LISTMONK_DB:-listmonk}
      POSTGRES_USER: ${LISTMONK_DB_USER:-listmonk}
      POSTGRES_PASSWORD: ${LISTMONK_DB_PASSWORD:?LISTMONK_DB_PASSWORD required}
    volumes:
      - backoffice-listmonk-pgdata:/var/lib/postgresql
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -h 127.0.0.1 -U ${LISTMONK_DB_USER:-listmonk} -d ${LISTMONK_DB:-listmonk}"]
      interval: 5s
      timeout: 5s
      retries: 20
    networks:
      - newsletter_net

  backoffice-backup:
    image: postgres:18@sha256:4ef4dbc939d61acea57712655ddb4b4ab27419c913f94cca0cd57cb3ea3c2280
    restart: unless-stopped
    logging: *logging
    user: "0:0"
    depends_on:
      umami-db:
        condition: service_healthy
      listmonk-db:
        condition: service_healthy
    volumes:
      - backoffice-backups:/backups
      - ./deploy/scripts/backup-loop.sh:/backup-loop.sh:ro
      - ./deploy/sql/umami-retention.sql:/umami-retention.sql:ro
    entrypoint: ["/bin/sh", "/backup-loop.sh"]
    environment:
      UMAMI_PGHOST: umami-db
      UMAMI_DB_USER: ${UMAMI_DB_USER:-umami}
      UMAMI_DB_PASSWORD: ${UMAMI_DB_PASSWORD}
      UMAMI_DB: ${UMAMI_DB:-umami}
      LISTMONK_PGHOST: listmonk-db
      LISTMONK_DB_USER: ${LISTMONK_DB_USER:-listmonk}
      LISTMONK_DB_PASSWORD: ${LISTMONK_DB_PASSWORD}
      LISTMONK_DB: ${LISTMONK_DB:-listmonk}
      BACKUP_HOUR: ${BACKUP_HOUR:-3}
      BACKUP_RETENTION_DAYS: ${BACKUP_RETENTION_DAYS:-14}
      UMAMI_RETENTION_DAYS: ${UMAMI_RETENTION_DAYS:-730}
    networks:
      - analytics_net
      - newsletter_net

networks:
  ingress_net:
  analytics_net:
  newsletter_net:

volumes:
  caddy-data:
  caddy-config:
  backoffice-umami-pgdata:
  backoffice-listmonk-pgdata:
  backoffice-backups:

3. Standardized Multi-Tenant Client Integration Contract

To maintain clean repository boundaries under SA-15, client applications (Pressroom, Wikantik, Stockroom) never access back-office databases with write permissions or manage service tables. Interaction is strictly mediated through HTTP APIs, client configuration, and read-only database grants.

1. Account Provisioning and API Contracts

Each client product is assigned a dedicated non-administrative service account within Umami:

\text{POST } /api/websites \quad \longrightarrow \quad \{\text{"id": "<uuid>", "name": "<site\_name>", "domain": "<site\_domain>"}\}

2. Client-Side Telemetry Contract

Browser telemetry avoids third-party tracking scripts. Client applications inject the tracking script via same-origin URLs:

<!-- Client Application Header (e.g., Pressroom or Wikantik) -->
<script async defer
        src="/analytics/script.js"
        data-website-id="0192e21b-4392-7104-9419-f5a1460d3d2c"
        data-auto-track="true"
        data-domains="blog.wikantik.com"></script>

Custom interaction events are tagged using declarative HTML5 attributes that Umami natively captures:

3. Cross-System Attribution via grafana_ro

While products write telemetry via Umami's HTTP ingest, stack-level observability tools and business reporting engines require structured SQL read access. The back-office suite provisions a dedicated PostgreSQL role grafana_ro with SELECT permissions restricted to an unprivileged reporting view:

-- deploy/sql/umami-views.sql
-- Owned by Back-Office Suite; consumed by JakeMon Grafana & SimpleAgilityAttributionRFC

CREATE OR REPLACE VIEW analytics_traffic AS
SELECT
    w.website_id,
    w.name AS website_name,
    e.created_at::date AS date,
    e.url_path,
    e.event_name,
    COUNT(DISTINCT e.session_id) AS unique_visitors,
    COUNT(*) AS total_events
FROM website_event e
JOIN website w ON e.website_id = w.website_id
GROUP BY w.website_id, w.name, e.created_at::date, e.url_path, e.event_name;

GRANT USAGE ON SCHEMA public TO grafana_ro;
GRANT SELECT ON analytics_traffic TO grafana_ro;

This view provides the foundation for marketing attribution joins defined in SimpleAgilityAttributionRFC, allowing Grafana dashboards on host inference to correlate blog reading volume with inventory sales in Stockroom without issuing expensive table scans across raw website_event partitions.

sequenceDiagram
    autonumber
    actor Reader as Site Reader (Browser)
    participant Caddy as Client Edge Caddy (docker1)
    participant BoCaddy as Backoffice Caddy (docker2)
    participant Umami as Umami Engine (docker2)
    participant DB as Umami PostgreSQL 18
    participant Grafana as JakeMon Grafana (inference)

    Reader->>Caddy: GET /analytics/script.js
    Caddy->>BoCaddy: Proxy GET to http://docker2.lan:8085/script.js
    BoCaddy->>Umami: Forward request
    Umami-->>Reader: Return tracker JavaScript

    Reader->>Caddy: POST /analytics/api/send (pageview beacon)
    Note over Caddy: Injects CF-Connecting-IP & X-Forwarded-For
    Caddy->>BoCaddy: Proxy POST to http://docker2.lan:8085/api/send
    BoCaddy->>Umami: Ingest beacon
    Umami->>DB: INSERT into website_event

    loop Scheduled Reporting
        Grafana->>DB: SELECT * FROM analytics_traffic WHERE date = TODAY
        DB-->>Grafana: Aggregated visitor & CTA counts
    end

4. Migration and Cutover Protocol

Migrating Umami and Listmonk from docker1 to docker2 is executed via logical database streaming with zero structural data loss.

Phase 1: Pre-Migration Provisioning on docker2

  1. Clone the back-office repository to /home/jakefear/source/backoffice on docker2.
  2. Generate production secrets into /backoffice/.env:
    UMAMI_APP_SECRET=$(openssl rand -hex 32)
    UMAMI_DB_PASSWORD=$(openssl rand -hex 24)
    LISTMONK_DB_PASSWORD=$(openssl rand -hex 24)
    LISTMONK_ADMIN_PASSWORD=$(openssl rand -hex 24)
    
  3. Create the external Cloudflare Tunnel DNS routes for analytics.wikantik.com and newsletter.wikantik.com pointing to 192.168.5.52:8085.
  4. Start the database containers on docker2 to initialize empty schemas:
    docker compose up -d umami-db listmonk-db
    

Phase 2: Live Export and LAN Transfer

  1. Trigger a clean PostgreSQL dump from Pressroom's current back-office containers on docker1:
    # Executed on docker1 inside Pressroom compose directory
    docker compose exec umami-db pg_dump -U umami -Fc umami > /tmp/umami_docker1.dump
    docker compose exec listmonk-db pg_dump -U listmonk -Fc listmonk > /tmp/listmonk_docker1.dump
    
  2. Transfer dumps across the private LAN to docker2:
    scp /tmp/umami_docker1.dump docker2.lan:/tmp/
    scp /tmp/listmonk_docker1.dump docker2.lan:/tmp/
    
  3. Restore dumps into the isolated docker2 database engines:
    # Executed on docker2
    docker compose exec -T umami-db pg_restore -U umami -d umami --clean /tmp/umami_docker1.dump
    docker compose exec -T listmonk-db pg_restore -U listmonk -d listmonk --clean /tmp/listmonk_docker1.dump
    
  4. Apply the grafana_ro user creation and reporting view scripts:
    docker compose exec -T umami-db psql -U umami -d umami < deploy/sql/umami-views.sql
    

Phase 3: Client Upstream Cutover and Validation

  1. Start the complete suite on docker2:
    docker compose up -d
    
  2. Update Pressroom's configuration on docker1 in /opt/pressroom/.env:
    # Redirect internal API and Caddy reverse proxy to docker2.lan
    PRESSROOM_ANALYTICS_UMAMI_APIURL=http://docker2.lan:8085
    PRESSROOM_NEWSLETTER_LISTMONK_BASEURL=http://docker2.lan:8085
    
  3. Remove docker-compose.backoffice.yml from COMPOSE_FILE in Pressroom's .env, and reload Pressroom:
    docker compose up -d --remove-orphans
    
  4. Verify end-to-end functionality:
    • Inspect Pressroom application logs on docker1 to confirm successful token refresh via POST http://docker2.lan:8085/api/auth/login.
    • Verify that browser telemetry beacons received at blog.wikantik.com/analytics/api/send return 200 OK from docker2.
    • Log into https://analytics.wikantik.com via Cloudflare Zero Trust authentication and verify that historical visitor graphs match pre-migration statistics.

Phase 4: 14-Day Rollback Window and Decommissioning

Following the safety precedent established in Pressroom's database isolation work:


5. Production Failure Modes and Operational Mitigations

Operating shared services across host boundaries introduces failure modes that do not exist in single-host deployments.

Failure ModeRoot CauseImpactMitigation & Recovery
Cross-Host LAN PartitionEthernet switch disruption or DHCP/IP drift between docker1 and docker2.Pressroom blogs fail to record analytics; newsletter subscription forms yield 503 errors. Blog page delivery remains unaffected.Pressroom's UmamiClient executes with strict 3-second connect timeouts and fails open. Reader page loads are never blocked. Alertmanager fires BlackboxProbeFailed on docker2.lan. Reconnect network interface or verify static ARP.
IP Anonymization / Geolocation FailureCaddy reverse proxy fails to forward client IP headers or omits trusted_proxies.Umami records all reader sessions as originating from 192.168.5.50 (cloudflare) or 192.168.5.51 (docker1).Caddy configuration pins trusted_proxies 192.168.5.50/32 192.168.5.51/32. Umami environment variable CLIENT_IP_HEADER=X-Forwarded-For is pinned in Compose. Automated integration test inspects incoming headers against known loopback IPs.
Database Disk SaturationHigh reader traffic accumulates raw website_event rows over extended operating cycles.PostgreSQL transactions fail; Umami rejects incoming beacons with HTTP 500.The backoffice-backup service executes an automated retention pruning job (umami-retention.sql) nightly following backup completion. Partitions older than UMAMI_RETENTION_DAYS (default: 730 days) are truncated.
Adblocker InterceptionReaders enable strict browser tracker blocking (uBlock Origin, Brave Shields).Analytics undercount page views and conversion events.Mitigated by design: trackers are served same-origin from the primary blog domain (/analytics/script.js), and beacon payloads are sent to /analytics/api/send. The script filename is configurable via TRACKER_SCRIPT_NAME.
Token Invalidation on Password RotationOperator rotates UMAMI_PRESSROOM_PASSWORD in the database without restarting Pressroom.Pressroom background reconciliation threads receive HTTP 401 on POST /api/websites.Pressroom's UmamiClient detects 401 responses, automatically triggers re-authentication against POST /api/auth/login, and caches the new bearer token without requiring an application restart.

See Also