Documentation Site C4 Model

이 문서는 FractalOps 문서 사이트 자체의 C4 모델입니다.

제품 아키텍처 C4는 FractalOps C4 Model이 소유하고, 문서 사이트의 소스, 빌드, 플러그인, 배포 경계는 이 문서가 소유합니다.

Level 1. Documentation Context

C4Context
  title FractalOps documentation site context

  Person(engineer, "Engineer / Operator", "문서를 읽고 운영 결정을 내린다.")
  Person(agent, "Agent / Scribe", "repository-owned docs source를 갱신한다.")

  System(docs, "FractalOps Docs", "Astro Starlight documentation site")

  System_Ext(github, "GitHub Repository", "docs/ source of truth and edit links")
  System_Ext(monstore, "docs.monstore.io", "Published documentation surface")
  System_Ext(starlight, "Astro Starlight", "Documentation framework")
  System_Ext(mermaid, "Mermaid", "Text-authored diagrams")
  System_Ext(panzoom, "panzoom", "Interactive pan and zoom for rendered C4 SVG diagrams")
  System_Ext(imagezoom, "starlight-image-zoom", "Zoomable documentation images")

  Rel(engineer, docs, "Reads docs and diagrams", "HTTPS")
  Rel(agent, github, "Edits Markdown source", "PR")
  Rel(github, docs, "Builds static site", "pnpm / Astro")
  Rel(docs, monstore, "Publishes static output", "GitOps / hosting")
  Rel(docs, starlight, "Uses")
  Rel(docs, mermaid, "Renders C4 and flow diagrams")
  Rel(docs, panzoom, "Enhances C4 Mermaid SVGs")
  Rel(docs, imagezoom, "Adds zoom behavior to images")

Level 2. Documentation Containers

C4Container
  title FractalOps documentation containers

  Person(reader, "Reader", "Human reader")
  Person(scribe, "Scribe Agent", "Documentation writer")

  System_Boundary(docs, "FractalOps Docs") {
    Container(content, "Docs Content", "Markdown", "Pages under docs/src/content/docs")
    Container(config, "Astro Config", "astro.config.mjs", "Starlight sidebar, Mermaid integration, C4 pan/zoom hook, image zoom plugin")
    Container(build, "Static Build", "Astro", "astro check and astro build")
    Container(search, "Pagefind Index", "Starlight default", "Static search index")
    Container(site, "Published Site", "Static HTML/CSS/JS", "Reader-facing documentation")
  }

  System_Ext(github, "GitHub", "Repository source and PR review")
  System_Ext(monstore, "docs.monstore.io", "Published hostname")

  Rel(scribe, github, "Submits docs source edits", "Pull request")
  Rel(github, content, "Stores source")
  Rel(config, content, "Loads")
  Rel(build, content, "Compiles")
  Rel(build, config, "Applies")
  Rel(build, search, "Generates")
  Rel(build, site, "Outputs")
  Rel(site, monstore, "Served as")
  Rel(reader, monstore, "Reads", "HTTPS")

Level 3. Rendering Components

C4Component
  title Starlight rendering component view

  Container_Boundary(site, "Docs build and render path") {
    Component(markdown, "Markdown Pages", ".md content", "Authoritative docs source")
    Component(sidebar, "Starlight Sidebar", "configuration", "Autogenerated architecture, operations, requirements, colocated sections")
    Component(mermaid_plugin, "astro-mermaid", "Astro integration", "Client-side rendering for Mermaid fenced code blocks")
    Component(c4_diagrams, "Mermaid C4 Blocks", "Mermaid syntax", "C4Context, C4Container, and C4Component diagrams")
    Component(c4_panzoom, "C4 Pan/Zoom Hook", "Astro page script", "Attaches panzoom controls after astro-mermaid renders C4 SVGs")
    Component(image_zoom, "starlight-image-zoom", "Starlight plugin", "Zoom behavior for Markdown and MDX images")
    Component(pagefind, "Pagefind", "Starlight default search", "Static search index")
  }

  Rel(markdown, c4_diagrams, "Contains")
  Rel(sidebar, markdown, "Routes")
  Rel(mermaid_plugin, c4_diagrams, "Transforms at client side")
  Rel(c4_panzoom, c4_diagrams, "Adds drag pan, zoom controls, and reset")
  Rel(image_zoom, markdown, "Enhances images")
  Rel(pagefind, markdown, "Indexes")

Authoring Contract

Source of truth is docs/src/content/docs/.
Use .md unless an existing page already requires MDX.
Keep durable docs free of run/session incident logs.
Do not commit docs/dist/, .astro/, Pagefind output, or other generated artifacts.
Mermaid diagrams use fenced mermaid blocks. C4 diagrams use C4Context, C4Container, and C4Component.
C4 Mermaid SVG pan/zoom is supplied by panzoom through docs/src/integrations/mermaid-pan-zoom.mjs.
Image zoom is supplied by starlight-image-zoom; it is for images, not the C4 Mermaid SVG viewport.
Validate with pnpm --dir docs build.

Current Plugin Baseline

The docs site uses these package baselines:

Capability	Package	Reason
Documentation framework	`@astrojs/starlight`	Starlight is the repository documentation framework.
Mermaid rendering	`astro-mermaid`	Renders Mermaid fenced code blocks without a headless browser build dependency.
Diagram grammar	`mermaid`	C4 and flow diagrams stay text-authored in Markdown.
C4 diagram pan/zoom	`panzoom`	Adds drag pan, zoom controls, and reset to rendered C4 Mermaid SVGs.
Image zoom	`starlight-image-zoom`	Starlight plugin for zoomable docs images.

Selection notes:

Starlight does not own Mermaid rendering as a built-in docs primitive here; the site uses astro-mermaid so Markdown remains plain .md and C4 blocks stay text-authored.
panzoom is used for C4 diagrams because starlight-image-zoom only targets documentation images and does not provide an SVG viewport for large Mermaid C4 diagrams.
The npm package named panout is not used; it is an old 0.0.0 placeholder and is not a Starlight or Mermaid pan/zoom implementation.
starlight-image-zoom remains adopted for Markdown and MDX images because it is Starlight-specific and avoids custom image lightbox code.
Keep astro-mermaid before starlight() in docs/astro.config.mjs so Mermaid fenced blocks are transformed before Starlight renders the page.
Keep mermaidPanZoom() after astro-mermaid; it waits for pre.mermaid[data-processed] and only enhances C4 diagrams.
Keep starlight-image-zoom inside starlight({ plugins: [...] }); do not add a second ad hoc image zoom path.

Reference links checked on 2026-07-03:

When this baseline changes, update docs/package.json, pnpm-lock.yaml, docs/astro.config.mjs, and this page together.