API & Runtime Contracts

This reference collects the durable contract-style documentation that replaced the retired spec-kit contract files.

HTTP APIs

Architecture Overview: high-level API and authentication surfaces for browser, device, Caddy, Ash JSON:API, and E2E consumers.
Client-Server Interface: Go client /api/v1, E2E /e2e, authentication, response shapes, and error handling.
OpenAPI Contracts: maintained OpenAPI definitions for bespoke Phoenix controller APIs that are not generated by Ash.
Server Web: browser routes, JSON routes, E2E routes, and terminal channel surface.
Server E2E: E2E run/result behavior and protocol expectations.

Client Transport: typed Go client HTTP boundary for registration, heartbeat, command results, and command payloads.
Client Command Handler: server-issued command execution boundary.
Client Starlark Runtime: .stary script parsing, validation, execution, and telemetry output behavior.
Client FRP Manager: FRPC lifecycle and remote-access token handling.

Server Devices: registration, approval, listing, remote access flags, pending commands, and terminal support.
Server Monitoring: heartbeat, telemetry, alerts, and offline checks.
Server Reporting: custom report and query builder behavior.

Deployment Compose: Compose services, required operator inputs, hostname contract, Caddy ask endpoint, and artifact rules.
Runtime Boundaries: process, network, data, secret, and test-only boundaries.

packages/server/priv/static/openapi.yaml documents the generated Ash JSON:API surface under /api/json.
The bespoke Phoenix controller APIs under /api/v1 and /e2e are documented by the OpenAPI files in OpenAPI Contracts and the human-readable references above; they are not covered by the Ash generated OpenAPI document.