01 — Architecture Assessment

Stack at a glance

Layer	Choice	Why
Static site generator	MkDocs Material	Markdown-native, near-zero ceremony, built-in client-side search, mature theme. Astro Starlight was the runner-up but adds JS framework complexity for no win on this content.
Hosting	Cloudflare Pages	Free, fast, Git-driven, integrates natively with Cloudflare Access. Already part of the Admin Dashboard architecture.
Auth	Cloudflare Access (existing IdP)	Adventive already uses Access for operator surfaces. Same identity, same policy model, same admin pane.
Source	Private GitHub repo	Same workflow as everything else; engineering edits via PR.
CI	GitHub Actions → Cloudflare Pages	Pages auto-deploys from the repo; no separate Action strictly needed, but a build-validation Action gives clean PR feedback.
Observability	Cloudflare Pages analytics + New Relic Browser (optional)	Pages analytics is free and usually sufficient. Add New Relic Browser only if engagement metrics matter to a stakeholder.

Why MkDocs Material specifically

• The content is plain Markdown with tables, code fences, and the occasional callout — exactly what MkDocs Material renders well.
• Search is built in (Lunr.js, client-side, no server). No Algolia account needed.
• Theme matches our visual idiom: clean sans-serif, accent color, three-pane layout (left nav, center content, right TOC).
• Admonitions (!!! note, !!! warning) map cleanly onto the WeasyPrint callout style we already use.
• Plugin ecosystem is mature: mkdocs-awesome-pages-plugin for nav, mkdocs-pdf-export-plugin if we ever want a “download as PDF” link, mkdocs-git-revision-date-localized-plugin for “last updated” stamps.

Repo layout (locked — see decisions/2026-04-27-repo-this-folder-becomes-source.md, amended 2026-04-27)

The Adventive Engineering/ folder IS the docs repo. Build/config files live at the repo root; all authored content lives under a single docs/ subdirectory (mkdocs.yml’s docs_dir: docs). The amendment was needed because MkDocs 1.6 forbids docs_dir: ..

Adventive Engineering/                     ← git repo: adventive/adventive-engineering-docs
├── mkdocs.yml                             # docs_dir: docs
├── requirements.txt                       # mkdocs-material + plugins (pinned; pygments<2.20)
├── .gitignore
├── README.md                              # Thin GitHub-browser README
├── .github/
│   └── workflows/
│       └── build.yml                      # PR validation (mkdocs build --strict)
├── overrides/                             # Material theme partial overrides
│   └── partials/copyright.html
└── docs/                                  # ← docs_dir
    ├── README.md                          # Site landing page
    ├── assets/extra.css                   # Adventive theme CSS (must live inside docs_dir)
    ├── projects/
    │   └── .pages                         # Explicit nav order
    ├── platform/
    │   ├── .pages
    │   └── cloudflare/.pages
    ├── _templates/                        # Excluded from rendered site
    ├── _shared/                           # Excluded from rendered site
    ├── _archive/                          # Excluded from rendered site
    └── _proposed/                         # Excluded from rendered site

PDFs and the source Markdown are committed alongside each other. mkdocs.yml’s docs_dir: docs points at the content root, and exclude_docs: removes the underscore-prefixed folders and the per-project code/, inputs/, handoff/, connector-rewrite/, and worker-stub/ subfolders from the rendered site.

Auth design (locked — see decisions/2026-04-27-idp-jumpcloud.md)

• Single self-hosted Access application protecting docs.adventive.dev/*.
• Identity provider: JumpCloud (SAML).
• Policy: Email ends with @adventive.com AND Group is engineering-docs-readers (JumpCloud group).
• Session: 24h.
• Service-token policy added as a fallback for CI/automation that needs to fetch the site.
• No public path — everything is gated. If a page ever needs to be public, carve it out with a separate Access app on a subpath rather than weakening the main policy.

What this is NOT

• Not a CMS. Editing happens locally in your editor of choice, committed to git.
• Not a wiki. There’s no in-browser editing or per-page comments (yet).
• Not a replacement for the WeasyPrint PDFs. The PDFs are still produced per the house style and remain the formal deliverable for any project that requires one.