Skip to content

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 .tf files
  • 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 out cookiehub/infra at build time
  • Runs terraform-docs markdown per module → writes to docs/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/main receives a push, it fires a repository_dispatch event to docs/
  • 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 repo scope stored as a secret in infra/

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'
            })