morz-infoboard/docs/plans/2026-03-22-backend-agent-status-design.md

Backend-Agent Status Slice Design

Goal: Stabilize the current backend foundation and add the first small, real backend-agent status path without introducing database or MQTT dependencies yet.

Architecture: The backend keeps its existing in-memory/runtime-only character, but gains stronger HTTP test coverage and a minimal player status ingestion endpoint. The agent reuses its internal health snapshot and posts a compact status payload to the backend on a timer, so the first end-to-end data flow is exercised before larger sync and broker work begins.

Tech Stack: Go stdlib HTTP server/client, existing repo docs, existing agent health model.

---

Decision

For the next slice, we intentionally do not implement full player registration, persistence, authentication, or MQTT.

Instead we build a narrow vertical slice with these boundaries:

1. harden existing backend routes and validation coverage
2. add POST /api/v1/player/status in the backend with shared error handling
3. add a small agent status reporter that periodically sends the current health snapshot
4. document the temporary v1-dev contract clearly so later persistence and auth can replace it cleanly

Why this order

Option A - Recommended: backend hardening, then minimal status path

Pros:

• least architectural churn for the current repo stage
• gives the project its first real backend-agent integration
• keeps risk low because the payload is small and derived from already tested agent state
• creates a natural foundation for later registration, revisions, and MQTT state

Cons:

• still not very visible to end users
• uses temporary in-memory handling on the backend

Option B - Agent-first connectivity expansion

Pros:

• fast to implement in the agent
• extends the new health model quickly

Cons:

• creates local connectivity logic without a meaningful server contract
• duplicates future work once the backend path exists

Option C - Bigger vertical slice with registration and status

Pros:

• closer to the eventual architecture
• more obviously “real” system behavior

Cons:

• too much surface area for the current codebase maturity
• would mix lifecycle hardening, API design, auth placeholders, and agent behavior at once

Scope

Backend

• keep GET /healthz, GET /api/v1, GET /api/v1/meta, and the existing message-wall route
• add route-level tests for the existing endpoints
• expand message_wall validation tests to match the documented rules more closely
• add POST /api/v1/player/status
• accept a small JSON payload and respond with a compact acknowledgement
• no database write, no in-memory historical store yet beyond the request/response path unless needed for tests

Agent

• keep the current lifecycle and health snapshot model
• add an HTTP status reporter component that transforms the snapshot into a backend payload
• send periodic status updates on a configurable interval
• keep failures non-fatal and log them as structured events
• no registration, no retries beyond the next normal interval, no MQTT yet

Proposed temporary API contract

Request

POST /api/v1/player/status

{
  "screen_id": "info01-dev",
  "ts": "2026-03-22T16:00:00Z",
  "status": "running",
  "server_url": "http://127.0.0.1:8080",
  "mqtt_broker": "tcp://127.0.0.1:1883",
  "heartbeat_every_seconds": 30,
  "started_at": "2026-03-22T15:59:30Z",
  "last_heartbeat_at": "2026-03-22T16:00:00Z"
}

Response

{
  "status": "accepted"
}

Notes

• this is a dev-stage HTTP substitute for the richer future status/heartbeat model described in API-MQTT-VERTRAG.md
• the payload is deliberately derived from fields the agent already owns today
• later player identity, auth, richer connectivity flags, and persistence can evolve this contract without invalidating the current slice

Error handling

• invalid JSON -> existing shared API error envelope with 400
• missing screen_id or invalid timestamps -> shared API error envelope with 400
• successful ingest -> 200 with compact acknowledgement
• agent-side send failures -> structured log event, but the agent keeps running

Testing strategy

Backend tests

• route tests for /healthz, /api/v1, /api/v1/meta
• route tests for valid and invalid POST /api/v1/player/status
• broaden message_wall validation tests for version, unit, fit mode, duplicate slots, out-of-bounds slots, empty slots

Agent tests

• reporter payload generation from HealthSnapshot
• status send success path using httptest.Server
• non-fatal error handling on send failure
• interval-driven reporting using injectable ticker/clock seams where needed

Out of scope

• database persistence of player status
• player registration
• auth tokens
• MQTT broker integration
• screenshots and media sync
• admin UI visualization of the status data

Expected result

After this slice, the repository still remains intentionally simple, but it gains:

• hardened backend route and validation coverage
• the first real backend-agent HTTP interaction
• a cleaner base for later registration, sync, and MQTT work