Gå til indholdet

ADR-0002 — C4-model med LikeC4 (DSL-først) + MkDocs/Cloudflare-portal

  • Status: accepteret
  • Dato: 2026-07-21
  • Beslutningstagere: Allan (+ Danny)

Kontekst

Al arkitektur — nuværende og fremtidig — skal dokumenteres struktureret. Vi vælger C4-modellen (Context → Container → Component → Code; vi bruger normalt kun Context + Container). Vi vil kunne vise dokumentationen som et pænt, privat site nu og senere have en rigtig, interaktiv C4-viewer — uden at skulle tegne diagrammerne om.

Krav/rammer: dansk, git-baseret (diagrams-as-code), lav drift for et 2-mands ikke-devops-team, TypeScript som husets standardsprog, privat (forretningsdokumentation), gerne gratis hosting uden VPS.

Beslutning

Vi adskiller tre lag, så kun ét nogensinde skal "erstattes":

  1. Model (single source of truth): LikeC4-DSL (arkitektur/c4/*.c4). Én model → mange views.
  2. Portal: MkDocs + Material for MkDocs, hostet på Cloudflare Pages (auto-build ved git-push, ingen VPS) + Cloudflare Access (privat, låst til vores e-mails). Diagrammer embeddes som eksporterede billeder (likec4 export png).
  3. Rigtig C4-viewer (senere): LikeC4's egen interaktive build (likec4 build) som et separat Cloudflare Pages-site fra samme .c4-kilde — nul genoptegning; det er "kun" en viewer-swap.

C4-konventioner: minimum Context + Container pr. system; Code-niveau springes over; ét diagram = ét view; C4-"Container" ≠ Docker/OCI-container (defineres eksplicit i arkitektur/c4/README.md).

Alternativer overvejet

  • Mermaid-først (i MkDocs): lavest friktion nu, men Mermaid-kilden kan ikke indlæses af en rigtig C4-viewer senere → kræver genoptegning. Fravalgt fordi vi eksplicit vil undgå genoptegning.
  • Structurizr DSL: industristandard for "én model → mange views", men Java-baseret (mismatch med vores TS-stak) og midt i en "vNext"-konsolidering (EOL-churn på Lite/CLI/cloud). Fravalgt til fordel for LikeC4.
  • IcePanel: kommerciel SaaS, ikke diagrams-as-code i git. Fravalgt (lock-in + ikke git-native).
  • Flyt alt til docs/ for "rent" MkDocs: ville bryde alle relative krydslinks + sti-referencer i issues/artifacts/agent-filer. Fravalgt; vi bruger i stedet mkdocs-same-dir (docs i repo-roden).

Konsekvenser

Positive: LikeC4 er MIT, Node/TS-native (matcher vores stak), har VS Code-extension, MCP-server (AI-native) og kan både eksportere billeder nu og være den interaktive viewer senere fra samme kilde. Portalen (MkDocs/Cloudflare) er permanent og genbruges uanset viewer.

Negative / at holde øje med: - LikeC4 udgiver hyppigt → pin eksakt version (likec4@1.59.1) og test opgraderinger. Node ≥ 22 kræves. - PNG-eksport kræver Playwright/Chromium (tungt i CI) → vi rendererer lokalt og committer billederne indtil vi evt. sætter en CI-render op. Ingen native SVG-eksport pr. v1.59. - MkDocs med docs i repo-roden kræver mkdocs-same-dir (monkeypatch) + et build-workaround på Cloudflare (site_dir: ../site → mv til _site). Verificér lokalt (mkdocs serve) før Cloudflare kobles på. - Værktøjsvalg er "dyrt at lave om" → derfor denne ADR. Ændres det, skrives en ny ADR der superseder denne.

Se opsætning: ../c4/README.md (C4-guide + render) og ../../docs-portal.md (MkDocs/Cloudflare).