browser/openspec/changes/implement-platform-observability-and-config-read/design.md

Context

The current frontend calls /metrics/platform, /metrics/server-instances, and /server-instances/{id}/config, but the backend router does not implement them. HomePage falls back to partial data or error states, and ServerDetailPage uses a hardcoded server.properties sample when config read fails.

This change is deliberately read-only. It creates the observability/config read surface needed by later config write, AI suggestion, and run execution changes without introducing file mutation or process orchestration.

Goals / Non-Goals

Goals:

• Implement platform resource usage and per-server metrics API routes.
• Implement safe server config read route with role-scoped access.
• Keep response contracts bounded and free of secrets, host paths, direct sockets, and raw run credentials.
• Update frontend pages to consume real API data and demote local samples to explicit fallback.
• Add service/API/frontend tests and browser walkthrough evidence.

Non-Goals:

• No config write, file write, or diff approval routes.
• No external metrics collector or long-term metrics storage backend.
• No browser log tail, artifact transfer UI, or AI log analysis.
• No run worker changes beyond existing data sources.

Decisions

Decision 1: Keep metrics as platform-owned read models

The service will expose platform and server metrics through platform DTOs. Initial values may be derived from existing run endpoint/server/job metadata or stored in the in-memory repository, but callers see stable read contracts.

Alternative considered: let the frontend compute all metrics locally from server lists. Rejected because the console already has API client methods and future run workers need a platform-owned metrics surface.

Decision 2: Server config read returns logical content only

The config read response returns server instance ID, config version, content, format/key metadata, and timestamps. It must not include host filesystem paths or run-local socket details.

Alternative considered: return a host path for browser editing. Rejected because run paths must not leak to platform_web or plugins.

Decision 3: Role-scoped access applies to config and server metrics

Platform administrators can read all metrics/config. Server owners and administrators can read only their server instances. This reuses the existing bearer session and ACL behavior.

Decision 4: Frontend fallback remains visibly non-production

Local sample config can remain only as an explicit fallback state for API-unavailable development/demo flows. Production rendering must prefer API data and show errors/empty states honestly.

Risks / Trade-offs

• [Risk] Derived metrics can look less live than future run telemetry. Mitigation: expose source/timestamp fields and keep later real-time collectors as a separate change.
• [Risk] Config content may be stale relative to actual files until run worker integration exists. Mitigation: include config version and source metadata.
• [Risk] Server detail can still show fallback config if backend is unavailable. Mitigation: label fallback clearly and add tests that API success suppresses fallback.

Migration Plan

1. Add metrics/config domain, DTO, validators, and service methods in platform/.
2. Add API handlers/routes and route documentation updates.
3. Update platform_web API types/views to render API metrics/config.
4. Add tests and browser walkthrough.

Open Questions

• Whether future metrics persistence should be a repository table or a projection from run heartbeats/logs.
• Whether config format should start as plain text only or include structured sections after file dispatch is implemented.