Technical Decisions¶
The reasoning behind how this site is built, recorded when the site was set up (March 2026). It is a decision record, not a plan: the plan it came from has been retired and lives in git history. Release and branching decisions are recorded in Branching and Releases.
Doc Framework — MkDocs + Material¶
Chosen: MkDocs with Material theme
Rationale:
- Static site — fast, zero runtime, easy to host anywhere
- Material theme has best-in-class search, navigation, and code block rendering out of the box
- Markdown-native — no MDX, no React, no build complexity
- Strong ecosystem:
mkdocs-material,terraform-docs, Mermaid plugin, D2 plugin
Alternatives considered:
- Docusaurus — powerful but heavyweight for ops docs; React build adds complexity for no benefit here
- Plain markdown in
infra/— no navigation, no search, poor cross-referencing - Notion — collaborative but drift-prone, no git, hard to enforce structure or automation
Hosting — Cloudflare Pages¶
Chosen: Cloudflare Pages
Rationale:
- Free tier, fast global CDN
- Native GitHub integration — push to main triggers a deploy
- Already using Cloudflare for DNS and CDN across other services
- Works seamlessly with Cloudflare Access for authentication
Alternatives considered:
- Vercel — already used for other projects, but Deployment Protection (SSO) costs an additional $150/month
- GitHub Pages — simple, but no built-in authentication without hacks
Access Control — Cloudflare Access + Azure AD¶
Chosen: Cloudflare Access with Microsoft 365 (Azure AD) as identity provider
Rationale:
- Team uses Microsoft 365 / Outlook — Azure AD is the natural SSO provider
- Cloudflare Access free tier supports up to 50 users
- Provides audit logs, session management, and per-path policies if needed
- No shared passwords — engineers authenticate with their existing Microsoft accounts
- Zero-trust model: docs are never publicly accessible even if the URL leaks
Security note: Keeping docs private is correct, but the underlying systems must be secure regardless of whether the docs are exposed. Don't rely on obscurity as a security control — use it as an additional layer only.
Architecture Diagrams — D2 + Mermaid¶
Chosen: D2 for architecture/network diagrams, Mermaid for sequence/flow diagrams in runbooks
Rationale:
- Both are diagram-as-code — committed to git, diffable, no exported PNGs
- D2 handles complex nested diagrams (like the full infrastructure overview) with better layout control
- Mermaid renders natively in GitHub and in MkDocs without extra tooling — ideal for inline runbook flows
- D2 requires a build step but produces cleaner output for the complexity of the infra diagram
State today
No .d2 sources have been committed yet; every diagram on the site is Mermaid. D2 remains the choice if a
diagram outgrows Mermaid's layout.
Alternatives considered:
- Mermaid only — layout gets unwieldy for the full architecture diagram
- draw.io / Lucidchart — not code, can't diff, drift-prone
Terraform Docs — terraform-docs (auto-generated)¶
Chosen: terraform-docs run at build time against a live checkout of infra/
Rationale:
- Module docs (inputs, outputs, resources) are generated directly from
.tffiles - Can never go stale — docs are always in sync with the actual Terraform modules
- Zero manual maintenance required for the reference layer
Implementation:
docs/GitHub Actions workflow checks outcookiehub/infraat build time- Runs
terraform-docs markdownper module → writes todocs/docs/infrastructure/modules/ - Generated files are never committed to
docs/— always rebuilt fresh
Cross-Repo Trigger¶
Chosen: repository_dispatch event from infra/ to docs/
Rationale:
- When
infra/mainreceives a push, it fires arepository_dispatchevent todocs/ - Docs site rebuilds automatically — always reflects latest Terraform module state
- Clean separation:
infra/doesn't know about docs structure, just fires an event - Requires a PAT with
reposcope stored as a secret ininfra/
Implementation sketch:
# infra/.github/workflows/trigger-docs.yml
on:
push:
branches: [main]
jobs:
trigger:
runs-on: ubuntu-latest
steps:
- uses: actions/github-script@v7
with:
github-token: ${{ secrets.DOCS_REPO_PAT }}
script: |
await github.rest.repos.createDispatchEvent({
owner: 'cookiehub',
repo: 'docs',
event_type: 'infra-updated'
})