# 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`

```json
{
  "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

```json
{
  "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