Engineering Principles

Summary

The platform is built around composability, explicit ownership, auditability, and future optionality. Velocity matters, but it is not allowed to erase the boundaries that make later work possible.

Problem

Operational platforms fail when convenience becomes architecture. A route starts querying analytics tables directly, a job starts owning business state, or an integration leaks provider-specific shapes into internal code. Each shortcut can work locally while making the next domain harder.

Principle

Prefer durable primitives over isolated features. Code should make ownership obvious, carry context explicitly, and preserve a path to split services, databases, or surfaces later.

Platform Shape

The repo guidance asks every change to preserve separation of concerns across pipelines, jobs, services, integrations, UI, and stateful review. The architecture reference repeats the same posture: clarity over cleverness, explicit ownership, deterministic pipelines, audited state machines, integration boundaries, and failures captured as data.

The practical test is simple. If a capability might be reused by a job, API route, UI surface, or future agent, it should not live only inside the first caller. If a failure affects business meaning, it should become an issue, signal, or review state rather than disappearing into logs.

Source Evidence

  • AGENTS.md
  • docs/reference/architecture.md

Tradeoffs

These principles bias against clever shortcuts. The upside is that new domains can reuse existing platform behavior without copying hidden assumptions.

  • docs/engineering/reference/thin-jobs-fat-services.md
  • docs/engineering/concepts/failures-are-data.md