ITWorx-Pulse-Public/docs/engineering/BACKEND_STANDARDS.md

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.