Engineering Hub¶

The single source of truth for engineering governance: how we decide, what we adopt, what we are building toward, and why.

This is not a project management tool. Work is tracked in delivery repos and team boards. What lives here is the technical memory and direction of the organization — decisions, principles, technology positions, capabilities, and strategy — versioned, reviewable, and searchable for years.

Concept model¶

Every document type here plays one role, and they reference each other by stable IDs:

flowchart LR
    V[Vision] --> P[Principles]
    P -->|guide| RFC["RFC<br/>(GitHub Issue)"]
    RFC -->|accepted| ADR[ADR]
    ADR -->|codified as| STD[Standards]
    ADR -->|moves items on| TR[Tech Radar]
    ADR -.->|justifies| IMPL[Implementation PRs]
    CAP[Capabilities] -->|invested in via| INIT[Initiatives]
    INIT --> RM[Roadmap]
    INIT -.->|produce| RFC
    TR -.->|informs| CAP

A RFC is how we discuss a significant technical change (as a GitHub Issue).
An ADR is how we record the decision permanently (as a Markdown file).
The Tech Radar is our current position on every technology we use or watch.
Capabilities are the organizational abilities we invest in (e.g. Observability).
Initiatives are the large investments that grow capabilities.
Roadmaps sequence initiatives per quarter.
Principles and the Vision constrain and orient all of the above.
Standards are the enforceable rules that decisions produce.

Map of the repository¶

Directory	Contents	ID scheme
`vision/`	Engineering mission, north star, long-term goals	`VISION`
`principles/`	Engineering principles	`P-0001`
`tech-radar/`	Technology positions by quadrant and ring	`TECH-<slug>`
`adrs/`	Architecture Decision Records	`ADR-0001`
`rfcs/`	RFC process + archive of accepted RFCs	`RFC-0042` (= issue #42)
`capabilities/`	Engineering capabilities and maturity	`CAP-<slug>`
`initiatives/`	Large engineering investments	`INIT-<slug>`
`standards/`	Coding, architecture, security, operational standards	`STD-0001`
`architecture/`	System architecture docs and review process	`REV-0001`
`roadmaps/`	Quarterly engineering roadmaps	`ROADMAP-2026-Q3`
`templates/`	Templates for every document type	—
`schemas/`	JSON Schema for document frontmatter	—
`scripts/`	Validation, catalog build, scaffolding	—

How a decision flows¶

Open an RFC — a GitHub Issue using the RFC template. Discussion happens there.
The RFC moves through labels: rfc/draft → rfc/review → rfc/final-comment → rfc/accepted|rejected.
On rfc/accepted, automation opens a PR that archives the RFC into rfcs/ and scaffolds an ADR in adrs/ linked back to it.
The ADR is reviewed and merged via CODEOWNERS (Architecture Review Board).
Merging the ADR triggers notifications and, when applicable, a Tech Radar update.
Implementation PRs in delivery repos reference the ADR ID in their description.

Rules of the hub¶

Everything is versioned. Documents change only through pull requests.
Everything is owned. Every document has an owner and a next_review date; automation opens an issue when a review is overdue — nothing rots silently.
Everything is linked. Documents reference each other by ID in YAML frontmatter, so the relation graph is machine-readable (see AGENTS.md).
Everything is searchable. The repo publishes a documentation site with full-text search, plus a generated catalog.json for tooling and AI agents.

Quick starts¶

I want to…	Do this
Propose a significant technical change	Open an RFC issue
Propose adopting / retiring a technology	Open a Radar change issue
Record a decision already discussed	`make new type=adr title="..."` and open a PR
Request an architecture review	Open an Architecture review issue
Check our position on a technology	`tech-radar/` or the radar page on the site
Understand why something was built this way	Search `adrs/` or the site; follow `relations` in frontmatter

Documentation site¶

The hub is published with MkDocs Material to Cloudflare Pages, behind Cloudflare Access (organization SSO), on every merge to main — see ADR-0003 for the generator choice and ADR-0004 for hosting/auth. Run it locally:

pip install -r requirements.txt
make serve         # http://localhost:8000
make validate      # frontmatter + relation validation (also runs in CI)

Governance¶

Decision rights, the Architecture Review Board, escalation, and branch protection are defined in GOVERNANCE.md. Contribution and writing conventions are in CONTRIBUTING.md. Machine/agent conventions are in AGENTS.md.