Skip to content

Blueprint — Smart Documentation

This directory contains C4-level architecture documentation for the blueprint/ repo.

The three top-level docs follow the C4 model: 1. Project Overview → 2. Architecture Overview → 3. Workflow Overview → deep-dives.

Reading order

If you're new to the blueprint:

  1. 1. Project Overview.md — what the blueprint is, the technology stack, project structure, getting started.
  2. 2. Architecture Overview.md — C4 Level 1/2/3 diagrams, architectural patterns, key design decisions, module breakdown.
  3. 3. Workflow Overview.md — sequence diagrams for the three phase workflows + the day-to-day inner loop.

If you're working in the repo:

  • deep-dive/Bootstrap Package.md — the Python infra/scripts/bootstrap/ package: composition roots, installers, cross-cutting protocols, sample install sequence.
  • deep-dive/Phase 2 Pipeline.md — the 13-step Phase-2 pipeline, step-by-step rationale, idempotency mechanisms, smoke tests.
  • deep-dive/Phase 3 Pipeline.md — the 6-step Phase-3 pipeline, mint-PAT-via-gitlab-rails-runner trick, GitLab client + ci_render implementation details.
  • deep-dive/Tofu IaC Layer.md — the OpenTofu IaC, the bidirectional-mode preserve_stateful_data flag, the wipe-data provisioner.
  • deep-dive/Sample Apps.md — the four apps/ projects, the cross-project include: from shared-code, the per-project CI pipeline anatomy.

Source docs (canonical)

The docs in this directory are derived from these canonical sources (in priority order — if any disagreement, the table at AGENTS.md § 2 wins). Note: the canonical sources live outside this MkDocs docs/ tree (they're repo-rooted files), so they are referenced by path but not hyperlinked in this rendered site. To read the originals, browse the repo.

  • AGENTS.md — hard rules + layout map.
  • README.md — human-facing phase table + quick start.
  • spec.md — original assignment brief.
  • ../prereqs.md, ../phase-1.md, ../phase-2.md, ../phase-3.md, ../secrets.md — per-phase runbooks (in this MkDocs site).
  • infra/scripts/bootstrap/VERSIONS.json — pinned versions (sole source of truth).
  • .agents/skills/provision-phase-{1,2,3}/SKILL.md — agent runbooks.

Updating this directory

The smart-docs skill is read-only with respect to apps/, infra/tofu/, infra/scripts/bootstrap/ — it does not modify source files. To regenerate this directory, re-run the skill against the latest source.

When a deep-dive document disagrees with AGENTS.md, the AGENTS.md wins. Report the discrepancy in a PR review rather than silently updating the smart-doc.

Diagram conventions

  • flowchart TD for system context, container architecture, infrastructure topology.
  • graph TB / graph LR for component relationships within modules.
  • sequenceDiagram for multi-party workflows (Phase 1 prep, Phase 2 install, Phase 3 provisioning, the inner loop).
  • classDiagram for the Phase 2 / Phase 3 module class structures.

Mermaid's built-in C4Context / C4Container types are not used — their label rendering is too small to read inside nodes; the conventional flowchart TD with subgraph grouping produces the same conceptual diagram with readable labels.

What this directory is NOT

  • Not a quick-start guide — see /index.md.
  • Not an iteration loop — see the per-phase skills at .agents/skills/.
  • Not a code reference — see the source files themselves. This docs the structure and the contracts between layers; the source is the truth.