Every engineering org has a diagram in a wiki with a box labeled "Payment Service" that was renamed eleven months ago. The diagram is not wrong. It is a historical artifact, like a map of a city before the freeway was built.
What this article solves: How to keep architecture documentation honest as the codebase moves—without assigning a human to redraw boxes every sprint.
Who this is for: Staff engineers, architects, and tech leads tired of apologizing for outdated Confluence pages.
Why architecture docs rot faster than READMEs
READMEs shame people because they break builds. Architecture pages do not break anything. They just slowly lie.
Common failure modes:
- The big-bang diagram: One heroic Lucidchart export, never updated
- The ADR graveyard: Fifteen decisions, three implemented, twelve superseded
- The schema guess: Docs describe tables that migrations removed last quarter
The fix is not "more discipline." It is tying architecture narrative to sources that change when the system changes.
GitHub: where structure actually moves
GitHub PRs are mini architecture reviews. They say what moved, what was considered, and what shipped.
When documentation generates from PRs:
- Service boundaries update when packages split
- ADRs inherit review comments ("we rejected event sourcing because…")
- New hires click from summary to the exact merge that introduced a dependency
If your architecture story cannot link to a PR, it is opinion.
Supabase: when the schema is the architecture
For data-heavy products, half the "architecture" is tables, views, and RLS—not boxes and arrows.
Connecting Supabase lets docs reference:
- Which tables own which domain concepts
- What migrations changed last week
- Whether prod still matches what the doc claims
Skip Supabase if your service is a thin BFF over someone else's warehouse. Add it when engineers open the database dashboard to settle arguments.
Confluence: publish without forking reality
Enterprise teams are not ditching Confluence next Tuesday. Fine.
Use Confluence for the audience that needs a polished page—compliance, PMs, support. Use source-linked docs for the audience that needs truth—engineers shipping code.
The anti-pattern: manually copying PR summaries into Confluence every Friday. The better pattern: generated docs with links back to GitHub (and schema, when relevant) so Confluence stays a window, not a second codebase.
Google Drive: where the RFC actually lived
The authoritative design doc is often Payments_v4_FINAL.docx in Google Drive, while the implementation diverged in PR #902.
Link Drive when staff engineers still write RFCs there. The goal is not to ingest every slide deck—it is to connect the RFC to the PRs that implemented (or rejected) it.
A weekly architecture hygiene that does not suck
- One merged PR this week gets an architecture blurb (even small: "extracted billing client")
- Schema changes trigger a doc refresh if Supabase is connected
- Confluence index page links to source-linked entries, not duplicate prose
- Retire diagrams that no longer match
main—archive with a link to the PR that superseded them
What "in sync" actually means
Perfect diagrams are a myth. Sync means: when I read the doc, I can verify it in under two minutes.
- Link to PR
- Link to schema (if data matters)
- Link to the Confluence or Drive page stakeholders read
If verification is fast, engineers trust the doc. If verification requires archaeology, they go back to Slack.
Checklist
- Architecture docs cite at least one PR per major component
- Supabase connected for services where schema debates are weekly
- Confluence/Drive connected for official RFCs, not duplicated by hand
- Team agrees: no diagram without an owner and a "last verified" trigger (merge to main)
Architecture documentation should feel like a living index of decisions—not a museum wing.