Engineering Hub

The single source of truth for engineering decisions at Orchid: what we decided, why, and what we are still discussing.

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

Where we start

The hub has one job: bring ideas and record decisions.

That means two habits:

1. Have an idea or a significant technical proposal? Open an RFC.
2. Made a decision that shapes how we build? Record an ADR.

As decision volume grows, new modules (tech radar, principles, roadmaps…) can be added — each one proposed the same way as anything else here: through an RFC.

What is an RFC?

RFC — Request for Comments — is how we discuss before deciding. It is a structured proposal, opened as a GitHub Issue, that puts an idea in front of everyone affected while it is still cheap to change.

The concepts behind it:

• A problem, then a proposal. An RFC states the problem independently of any solution, then proposes something concrete enough to be rejected. Vague proposals can't be evaluated; concrete ones can.
• Alternatives and trade-offs are mandatory. "What else did we consider?" and "what do we knowingly give up?" — an RFC without them is an announcement, not a proposal.
• Anyone can open one. Seniority is not a prerequisite; evidence is.
• Discussion has a deadline. The lifecycle moves through labels: rfc/draft → rfc/review → rfc/final-comment → rfc/accepted | rfc/rejected. The Final Comment Period (≥ 5 working days) means silence can't block a decision forever.
• The discussion is preserved. Accepted RFCs are archived as Markdown in RFCs/; the issue keeps the full debate history.

→ Open an RFC · The RFC process in detail

What is an ADR?

ADR — Architecture Decision Record — is how we remember what we decided and why. It is a short Markdown file, one per decision, stored permanently in ADRs/ and changed only by pull request.

The concepts behind it:

• One decision per record. Not a design doc, not a spec — a single decision, captured with its Context (the forces at play), the Decision itself, its Consequences (good and bad), and the Alternatives that were rejected.
• Written for the engineer of three years from now. The test of a good ADR is that someone who wasn't in the room understands why — and doesn't re-litigate it.
• Immutable once accepted. New context doesn't edit an old ADR; it produces a new one that supersedes it. Both stay. The history of our thinking is part of the record.
• What counts as "significant": hard to reverse, affects more than one team, or constrains future choices. When in doubt, write it — a cheap record beats an expensive memory.

→ ADR template · The ADR rules in detail

How they fit together

The RFC is the conversation; the ADR is the memory.

flowchart LR
    IDEA[Idea] --> RFC["RFC<br/>(GitHub Issue — discussion)"]
    RFC -->|accepted| ADR["ADR<br/>(Markdown file — permanent record)"]
    ADR -.->|justifies| IMPL[Implementation PRs]
    RFC -->|rejected| CLOSED[Closed issue — still searchable]

• Every accepted RFC produces an ADR.
• Not every ADR needs an RFC: small-but-worth-remembering decisions, or urgent incident-driven ones, can be recorded directly — open the ADR PR within 5 working days of the decision.
• Implementation PRs in delivery repos cite the ADR ID — that is what makes "which decision justifies this code?" answerable years later.

How decisions get approved

• RFCs: anyone opens; the author drives the discussion; engineering leadership moves the labels. After a Final Comment Period of at least 5 working days, rfc/accepted or rfc/rejected is applied and automation posts the next steps.
• ADRs: merged with 2 approvals on the pull request (enforced by branch protection). Approval means "the record is faithful and complete", not "I would have decided the same".
• Everything changes through pull requests — no direct writes to main, humans and AI agents alike.

Conventions

• English only. Dates are absolute (2026-07-08). One decision per file.
• IDs are immutable and sequential: ADR-0001, ADR-0002… RFC IDs are their GitHub issue numbers: issue #42 → RFC-0042.
• Every document starts with a small YAML frontmatter block (id, title, status, owner, date, cross-link) — this keeps the hub machine-readable for tooling and AI agents.
• Section headings follow the templates — don't invent new structures.

Quick starts

I want to…	Do this
Propose a significant technical change	Open an RFC issue
Record a decision already made	Copy templates/adr.md into ADRs/ and open a PR
Understand why something was built this way	Search ADRs/ or the site

Documentation site

The hub is published with MkDocs Material to Cloudflare Pages, behind Cloudflare Access (organization e-mails only), on every merge to main. Run it locally:

pip install -r requirements.txt
make serve         # http://localhost:8000

One-time repository setup (branch protection, labels, Cloudflare) is documented in .github/SETUP.md.