Files

Gabriel Radureau 4823394e0e docs(vibe): add applications/ guidebook (webapp + url-shortener)

Tree-docs guidebook under vibe/guidebooks/applications/ documenting the common
app pattern and two contrasting archetypes, drilling into lab-ecosystem/01-factory
(bidirectional):

- README.md  : the shared app pattern (repo = Dockerfile + chart + optional iac +
  CI; ArgoCD app-of-apps; the <app> join key; .fr vs .lab ingress conventions) +
  a two-archetype comparison.
- webapp.md  : canonical Go + Postgres exemplar (chart, VaultAuth/Static/Dynamic
  CRDs, inline iac vs the shared app_roles module, CI); notes the current nuance
  that the live pod still uses the static pgbouncer_auth DATABASE_URL.
- url-shortener.md : Rust + SQLite-on-Longhorn-RWO counterpart (single replica,
  no iac/no Vault, CI mirrors the upstream image); the power-cut recovery story.

erp is referenced in prose only (its own guidebook lands next). Sibling-repo code
via full gitea URLs; 2 mermaid diagrams MCP-validated; zero dead links.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

2026-06-23 21:58:36 +02:00

4.4 KiB

Raw Blame History

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, and cms — 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

Rules to contribute

Use the tree-docs skill. 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.md index 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 a classDef palette 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.

4.4 KiB Raw Blame History