Gabriel Radureau
c00c4cdd5c
ADR-0002 Phase B. Makes postgres/iac, argocd, and the conventions docs
multi-environment-capable WITHOUT activating any sandbox yet — every app
stays prod-only, so this change is behaviour-neutral:
- postgres/iac `tofu plan` is a no-op (proven: the elision flatten keys
are bare app names, db=<app>, role=<app>_role — identical addresses)
- the argocd apps.yaml render is byte-identical (181→181 lines, diff
empty) since no app declares `envs`
postgres/iac:
- variables.tf: `applications` becomes set(object({name, envs=optional(["prod"])}))
- main.tf: a `local.app_instances` flatten of applications × envs keyed by the
elided instance id (env=prod → "<app>"); per-app resources iterate it and
reference each.key / each.value.{database,role}. For prod-only apps every
resource address + attribute is unchanged. (main.tf also got a full
`tofu fmt` pass — the pgbouncer function block reindents 4→2 spaces, which
is cosmetic; the correctness gate is the CI tofu plan, not the text diff.)
- terraform.tfvars: string entries → { name = "..." } objects.
argocd/templates/apps.yaml:
- after the prod Application, a `range $app_attr.envs` loop renders one extra
Application per non-prod env: name/namespace `<app>-<env>`, shared repoURL,
helm.valueFiles [values.yaml, values-<env>.yaml], per-env syncPolicy override.
Renders nothing while no app sets `envs` → prod render unchanged.
docs:
- doc/runbooks/new-web-app/conventions.md (FR, authoritative): new section
"Plusieurs environnements pour une même app" — elision rule, suffix rule,
snake-case owner-role exception, erp/erp-sandbox table, ADR-0002 link.
- vibe/guidebooks/lab-ecosystem/naming-conventions.md (EN mirror): the env
coordinate section + a "Two sandbox models" section reconciling the
separate-cluster (ADR-0001, names repeat) vs in-cluster sibling (ADR-0002,
<env> suffix) strategies; Last Updated bumped; ADR-0002 cross-links.
Activation (erp gets envs=["prod","sandbox"] in postgres tfvars + argocd
values + erp/iac) is Phase D, gated by its own plan review.
Refs ADR-0002 (factory#15). Phase A = tools#2 (merged). Phase C = erp#11 (merged).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
vibe > Guidebooks
Guidebooks
Status: Active Last Updated: 2026-06-23 Related: vibe runbooks · vibe shareouts · canonical docs under doc/
What a guidebook is
A guidebook is a tree-doc reference map of the lab: a navigable set of linked Markdown pages (a root index, per-folder README hubs, and leaf pages wired with breadcrumbs and bidirectional cross-references) whose job is to describe how the system is actually wired right now — components, the conventions that join them, and the data/control flows between them.
Guidebooks are descriptive maps, not procedures. They answer "how does this fit together?" For "how do I execute X step by step?" see the runbooks. For "why was it built this way?" see the architecture decision records under doc/adr.
%%{init: {'theme': 'base'}}%%
flowchart LR
classDef src fill:#2563eb,stroke:#1e40af,color:#fff
classDef proc fill:#059669,stroke:#047857,color:#fff
classDef store fill:#7c3aed,stroke:#6d28d9,color:#fff
SYS["Lab system<br>(factory + tools + cms)"]:::src --> GB["Guidebook<br>(tree-doc reference map)"]:::proc --> READER["Reader<br>(human or agent)<br>understands the wiring"]:::store
- The lab system spans three repos —
factory,tools, andcms— joined by the<app>naming convention. - A guidebook surveys that system and renders it as a tree-doc reference map: indexed folders, breadcrumb-linked leaves, Mermaid flow diagrams.
- A reader (a human onboarding, or an agent planning a change) consumes the guidebook to understand how the pieces wire together before touching anything.
Key maintenance rule
Important
If a component documented in a guidebook is altered, the guidebook page describing it MUST be updated in the same change. A reference map that drifts from reality is worse than no map — it sends readers (and agents) confidently down dead paths. Treat the guidebook edit as part of the diff, not a follow-up: the PR that changes the component is the PR that updates its guidebook page.
Index
| Guidebook | What it maps | Status |
|---|---|---|
| Lab ecosystem | End-to-end map of factory + tools + cms: repos, the <app> join key, secrets via Vault, CI/CD, ArgoCD, and the data/control flows that connect them |
✅ Active |
| Factory provisioning | Deep dive into how factory provisions everything: Ansible playbooks + roles and OpenTofu | ✅ Active |
| Tools | Deep dive into the lab platform services in the tools namespace (Vault+VSO, Prometheus, Grafana, CrowdSec, poolers, Redis, Plausible, ClickHouse) |
✅ Active |
| CMS | Deep dive into the public Nuxt site arcodange.fr + its Cloudflare DNS/tunnel/Turnstile and Zoho email IaC | ✅ Active |
| Applications | The deployed apps and the common pattern they share — webapp (Go + Postgres) and url-shortener (Rust + SQLite); erp has its own guidebook | ✅ Active |
| ERP | The lab’s Dolibarr ERP — its deployment on Postgres, its document storage + backup/restore, and the read-only ops CLI (the most data-critical app) | ✅ Active |
Rules to contribute
- Use the
tree-docsskill. Guidebooks are tree-docs: author and grow them with the skill so breadcrumbs, hubs, and cross-links stay consistent. - Breadcrumb spine on every file. The first line of each page is its breadcrumb trail: ancestors are relative links, the current page is the bold-unlinked last item, separator is
>(space-gt-space). - README hub per subfolder. Every folder carries a
README.mdindex hub: a table of its children (link + one-line summary + status), sorted by importance/sequence, never alphabetically. - Bidirectional links. When page A references page B as related, page B references A back. Use descriptive link text — never "here" or "this".
- Mermaid preferences. Begin each diagram with a
%%{init: {'theme': 'base'}}%%directive, define aclassDefpalette legible on both light and dark backgrounds (dark fills, light text), use HTML<br>for line breaks, and follow every diagram immediately with a numbered ordered list restating the same flow in words. - Status legend. ✅ done · 🟡 beta · 🔴 critical · ⚠️ known issue · ❌ disabled · ⬜ not started.
- Honour the maintenance rule above — update the relevant guidebook page in the same change that alters the component it documents.