ITWorx Pulse release export
bd774932d5
Public source validation / validate (push) Failing after 3m8s
126 lines
3.5 KiB
Markdown
126 lines
3.5 KiB
Markdown
# 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.
|