# Backend and worker standards

## Domain boundaries

Core packages define:
- entities and reconciliation;
- metrics query model;
- dashboard validation/versioning;
- events;
- alert state machine;
- incidents;
- authorization policies.

Adapters implement:
- PostgreSQL;
- Prometheus;
- Unraid;
- Docker/constrained collector;
- OIDC;
- probes;
- notifications.

Domain packages must not import HTTP handlers or concrete adapters.

## HTTP

- Route groups map to modules.
- Middleware order is explicit.
- Request body, query and path validation.
- Body size limits.
- Timeouts and cancellation.
- Stable error mapping.
- Structured request log with redaction.
- Health/live and readiness separated.
- No mutation route for host/Docker/storage.

## Worker

- Jobs have stable keys and schedules.
- Database lock/lease prevents duplicate execution.
- Work is idempotent.
- Retries are bounded with jitter.
- Poison/repeated failures become visible system status.
- Shutdown waits for bounded graceful completion.
- Job result counts and duration recorded.

## Prometheus adapter

- Server-side only.
- Timeout and concurrency semaphore.
- Semantic templates only by default.
- Parse upstream warnings and staleness.
- Protect metadata/label endpoints.
- Normalize errors to stable codes.
- Instrument query duration/series/points/cache.

## Inventory reconciliation

- Stable source alias mapping.
- Snapshot can be repeated safely.
- Missing item becomes tombstoned after source-specific policy, not immediately deleted.
- User overrides remain separate.
- Relation source/confidence retained.
- Changes create deduplicated events.
- Source failure does not tombstone all entities.

## Alerts

- Deterministic state machine.
- Evaluation transaction/locking.
- Clock abstracted in tests.
- Unknown data explicit.
- Rule versions immutable.
- Notification side effects use outbox/idempotency pattern or equivalent.
- Acknowledgement does not mutate underlying firing condition.

## Database

- Context-aware queries.
- Parameterized SQL.
- Transaction boundaries documented.
- Pool limits.
- Repository methods return domain types/errors.
- Integration tests against real PostgreSQL.
- No production reliance on SQLite semantics.

## Agent

- Read-only capability list.
- No generic command execution endpoint.
- Authenticated/mutually trusted channel if remote.
- Bounded payloads.
- Version/capability negotiation.
- Local cache only where safe.
- Every elevated mount/capability justified and tested.