tomevault-io Node Backend
Core Workflow
- Identify the runtime shape first. Confirm the entrypoint, package manager, framework, and execution model before editing: HTTP API, worker, queue consumer, cron process, or mixed runtime. Pull the actual lint, type-check, test, and build commands from
40-commands.md; do not guess from package scripts alone. - Draw boundaries before changing behavior. Keep transport (handler/controller), business logic (service/use-case), persistence (repository/data adapter), and external integrations in separate layers. Framework request/response objects should stop at the transport boundary; domain services should not depend on Express/Fastify/Nest request types.
- Lock edge contracts. Validate request bodies, query params, headers, queue payloads, and environment-derived config explicitly at the boundary. Keep response shapes, status codes, and error envelopes deterministic; if a contract changes, treat it as an API review, not a refactor.
- Audit async and background execution. Every async path needs ownership: who awaits it, who handles failure, and who stops it at shutdown. Check timeouts,
AbortSignalpropagation where supported, retry bounds, idempotency for workers/consumers, and dead-letter or poison-message behavior for background processing. - Review persistence and side effects together. Confirm transaction boundaries, outbox/event publication ordering, cache invalidation, and file/network side effects are consistent with the changed behavior. If a schema or queue-payload change is involved, verify currently deployed nodes can coexist safely during rollout.
- Check resource and latency controls. Downstream HTTP, DB, and cache calls must have bounded timeouts, connection-pool awareness, and no unbounded fan-out from one incoming request. Prefer explicit concurrency limits for batch work or scatter-gather flows instead of trusting event-loop throughput.
- Confirm operability. Health/readiness endpoints, startup config validation, structured logs, metrics/traces, and graceful process shutdown are part of correctness. Verify changed code paths still emit enough signal to diagnose timeouts, retries, partial failures, and queue lag in production.
- Validate changed paths with the real command set. Run lint, type-check, test, and build commands from
40-commands.md. When the change touches side effects, make sure tests cover both the request path and the side-effect path rather than only the happy-path return value.
Reference Guide
| Topic | Reference | Load When |
|---|---|---|
| Delivery checklist | references/checklist.md |
Any Node backend feature or review |
High-Risk Areas
- Auth/session behavior, queue semantics, streaming responses, schema migrations, cache invalidation, and major runtime/dependency upgrades should be treated as change-management events, not routine edits.
Constraints
- Do not mix transport shaping, business rules, and persistence in one handler or module.
- Do not leave fire-and-forget promises without lifecycle ownership or failure reporting.
- Do not add retries to non-idempotent writes unless there is a deduplication key or explicit compensating logic.
- Do not read environment variables deep inside request paths; resolve config at startup and inject it.
- Do not widen response shapes, status-code semantics, or message contracts silently.
- Treat migrations, queue payload changes, and framework major-version upgrades as high-risk and review them alongside rollout behavior.
Source: Shubchynskyi/garda-agent-orchestrator — distributed by TomeVault.