Architecture principles
How Engineering Runtime is shaped — and how seriously each rule is enforced.
A principle without a status is decoration; this page names the mechanism.
Editorial rule. Every page on this portal should answer: Why was this
built? What problem does it solve? Who owns it? How should future engineers
extend it? The code already answers how it is implemented.
| Status |
Meaning |
| enforced |
A script, hook, CI check, or GitHub setting fails the change if you break it |
| partly |
True in important places; not yet mechanically guarded everywhere |
| honour-system |
Agreed practice — trust and review, no automatic fail |
Principles
| # |
Principle |
Status |
Enforced by |
| 1 |
Documentation ships with implementation |
enforced |
Workspace §5a/§5b; product hub same-effort hooks; app-api check-route-inventory.sh / contract-reminder.sh |
| 2 |
External consumers integrate only through api.engineeringruntime.com |
enforced |
Control Plane {prefix} lockstep rule and HTML_ONLY surface list |
| 3 |
Runtime owns capabilities; App API owns external contracts |
enforced |
Catalog regeneration in app-api deploy-cloud-run; runtime does not publish a second HTTP contract surface |
| 4 |
Every component has a single owner |
honour-system |
Workspace CLAUDE.md §3 ownership tables; review |
| 5 |
Internal repositories remain private |
enforced |
GitHub repository visibility settings |
| 6 |
Published contracts are versioned and backward compatible |
partly |
/metadata/versions and catalog commit stamps publish identity; breaking-change CI not yet universal |
| 7 |
One source of truth beats synchronized copies |
partly |
Generators where they exist (catalog → api.; runtime ADRs → this portal via scripts/generate-runtime-adrs.sh) |
| 8 |
Internal architecture may change while contracts stay stable |
honour-system |
Review against published OpenAPI / catalog |
| 9 |
Components communicate through published interfaces, not repo knowledge |
partly |
True across hubs (CI/contracts only); within a hub, local siblings are intentional |
Two cores
Everything else is supporting ecosystem.
| Core |
Repo |
Role |
| runtime |
engineering-runtime |
Binary — providers, capabilities, policy, audit, portal client |
| app-api |
engineering-runtime-app-api |
Shared API (api.) — policies, audit, fleet, catalog, auth |
Docs, series, this portal, demo-ui, app-ui, CI, releases, capabilities samples —
support those cores. They must not invent behaviour the cores do not have.
Local siblings vs cross-hub
| Scope |
Rule |
| Inside a hub |
Relative paths (../…); hooks fire when you open the hub root |
| Across hubs |
CI / published contracts only — never require the other hub on disk |
Where to read next