Engineering standards

Repository shape

Target:

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.

3.5 KiB Raw Blame History