Architecture diagrams
All seven SVGs use the workspace's py-diagram-gen, py-sprite-kit, and
py-visual-kit libraries. They share a solid background, native SVG text,
consistent typography, and an accessible title and description.
| Diagram | Source |
|---|---|
| Parser packages | Actual imports in internal/parser/ and its shared repository packages |
| Public packages | Actual imports in pkg/, packed by connected component |
| CLI command dispatch | The command switch in cmd/fi-fhir/main.go, resolved against functions across the CLI package |
Package arrows mean imports. Standard-library and third-party dependencies are omitted; packages with no connections in the displayed graph have a separate inventory. The renderer does not add edges to arrange the layout.
The CLI figure shows top-level command dispatch, not a complete call graph or a runtime trace. It intentionally omits help/version and handler internals. A new command fails generation until its presentation group is updated, so cross-file handlers cannot silently disappear from the figure.
Regenerate all diagrams
From the repository root:
make docs-diagrams
This regenerates the three code views above and all four conceptual diagrams, including the README illustrations.
narratives.yamlowns conceptual copy, rows, bands, and links.generate-diagrams.pyruns shared Go analysis and validates the generated SVGs.diagram_artwork.pycomposes the shared vector primitives and design tokens. Graphviz routes actual package-import edges.- Mermaid files are generated fallbacks, not a second editable source.
Generation rejects empty SVGs, duplicate IDs, non-static content, overflowing card heights, and ungrouped CLI commands. Review the rendered output at README width before committing; these checks do not replace a visual review.
Prerequisites:
uvand Python 3.11–3.13;uvresolves the script's declared dependencies.- Workspace checkouts of
py-diagram-gen,py-sprite-kit, andpy-visual-kitunder~/workspace/libs, or setDIAGRAM_LIBS=/path/to/workspace/libs. - Graphviz (
dot) for the package diagrams.
The SVG generator no longer requires Node.js, Mermaid CLI, or Chrome.
make docs-mermaid # Conceptual SVGs and Mermaid fallbacks
uv run scripts/generate-diagrams.py --only code
Commit the editable sources and generated artifacts together. Keep native text and the solid background so the diagrams remain crisp and readable in both GitHub and GitLab themes.