Publish ITWorx Pulse source

docs/engineering/ENGINEERING_STANDARDS.md

@@ -0,0 +1,125 @@
+# Engineering standards
+
+## Repository shape
+
+Target:
+
+```text
+apps/
+  web/
+  api/
+  worker/
+  agent/
+packages/
+  contracts/
+  ui/
+  test-fixtures/
+internal/
+  domain modules or Go internal packages
+config/
+deploy/
+tests/
+docs/
+artifacts/evidence/
+```
+
+Codex may refine the shape through an ADR, but privilege boundaries and clear ownership must remain.
+
+## General
+
+- Optimize for correctness, observability and maintainability.
+- Keep changes vertically complete.
+- Validate external inputs at boundaries.
+- Avoid global mutable state.
+- Use deterministic IDs/fingerprints where required.
+- Use UTC internally.
+- Add correlation IDs to request/job/event paths.
+- Preserve error causes and add context.
+- Never log secrets.
+- Use feature flags only when they have an owner, default and removal plan.
+
+## Git and commits
+
+- Focused commits aligned to task IDs.
+- Commit message format: `<TASK_ID>: <imperative summary>`.
+- Do not rewrite shared history.
+- No force push or destructive reset.
+- Keep generated evidence out of commits only when too large; summaries remain.
+- Tag releases only after final acceptance.
+
+## Go
+
+- Current supported stable Go version selected during M0 and recorded.
+- `go fmt`, `go vet`, static analysis and tests required.
+- Context propagated through I/O boundaries.
+- Errors wrapped with operation context.
+- Interfaces defined near consumers; avoid interface proliferation.
+- Goroutines have ownership, cancellation and bounded lifetime.
+- Worker jobs are idempotent.
+- SQL is parameterized; transactions explicit.
+- Migrations are forward/recovery tested.
+- HTTP handlers contain no core domain logic.
+
+## TypeScript/React
+
+- Strict TypeScript.
+- No `any` except narrow justified boundary adapters.
+- Runtime validation for external JSON.
+- Components separate data orchestration from presentation.
+- Server state uses a deliberate query/cache layer.
+- Live chart buffers do not live in broad global state.
+- Effects are cancellable and cleanup subscriptions.
+- Accessible semantic HTML first.
+- All user copy goes through localization.
+- Avoid giant components and prop drilling; centralize domain-specific hooks appropriately.
+
+## API and contracts
+
+- OpenAPI/JSON Schema is validated in CI.
+- Breaking changes are versioned.
+- Generated types are reproducible.
+- Error codes are stable.
+- Pagination, filtering and sorting are bounded.
+- Every endpoint has authz tests.
+- WebSocket messages are schema validated.
+
+## Database
+
+- Explicit migrations, no startup auto-mutation outside migration command.
+- Indexes justified by access path.
+- Constraints enforce invariants where practical.
+- JSONB payloads have size/schema limits.
+- Optimistic concurrency for user-edited versioned resources.
+- Timeouts and connection pool limits.
+- Test upgrade, restart, backup and restore.
+
+## Configuration
+
+- `.env.example` documents non-secret values.
+- Startup validates configuration and reports all invalid fields.
+- Secrets use secret files/runtime injection when possible.
+- No environment-specific values embedded in images.
+- Production and test compose overrides are separate.
+- Feature capability detection is visible in UI/system status.
+
+## Observability
+
+Pulse emits:
+- structured logs;
+- internal metrics;
+- health/readiness;
+- job status;
+- trace/correlation IDs;
+- redacted upstream error classes.
+
+Avoid recursive monitoring dependence: an external dead-man check must detect total Pulse failure.
+
+## Documentation
+
+Behavioral changes update:
+- relevant specification;
+- API/schema;
+- runbook if operational;
+- evidence;
+- current state;
+- ADR when architectural.