Publish ITWorx Pulse source

docs/engineering/BACKEND_STANDARDS.md

@@ -0,0 +1,95 @@
+# 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.