Diagrams Workflow

• Status: Ready
• Tooling: Draw.io source files plus exported SVG assets for VitePress

Recommendation

Use Draw.io for editable source diagrams and export SVG files for the docs site.

This keeps the diagrams:

• editable by humans
• crisp in VitePress
• easy to version in git
• independent from a custom docs plugin

ASCII First

For course content, prefer a two-step diagram workflow:

1. add a small ASCII diagram directly in the Markdown page when it helps explain the idea immediately
2. add a Draw.io brief for the stronger long-term diagram asset

This works well for the repo because ASCII diagrams are:

• fast to create and review
• easy to keep close to the explanation
• readable in diffs and pull requests
• good enough for early architecture, sequence, and state sketches

Use ASCII diagrams first for:

• state transitions
• project or layer maps
• short runtime flows
• ownership boundaries

Use Draw.io when:

• the concept is central enough to deserve a reusable visual
• the diagram will likely be reused across multiple pages
• grouping, swimlanes, or layout matter more than raw speed

Folder Convention

Use this structure:

• docs/diagrams/source Editable .drawio files.
• docs/diagrams/rendered Exported .svg files referenced by docs pages.

Diagram Brief Format

Before drawing, create a diagram brief in the related course or architecture page with:

• Title
• Purpose
• Audience
• Nodes
• Edges
• Groups or swimlanes
• Annotations
• Caption
• Suggested file paths

ASCII Diagram Pattern

When a page benefits from an inline sketch, keep it compact and readable. Good patterns include:

• box-and-arrow flow
• small state transition map
• layer stack
• actor-to-service sequence sketch

Example:

Operator
   |
   v
MainWindow -> MainViewModel -> WorkflowService -> AppStateStore
                                              |
                                              v
                                           AppState
                                              |
                                              v
                                           WPF UI

The ASCII version should clarify the explanation immediately. The Draw.io brief should preserve the idea for later polished rendering.

Initial Diagram Set

These are the first diagrams worth creating:

1. system-context.drawio
2. project-layer-map.drawio
3. domain-model.drawio
4. workflow-state.drawio
5. start-run-sequence.drawio
6. fault-recovery-sequence.drawio
7. recipe-loading-flow.drawio
8. run-history-flow.drawio

SVG Export Guidance

Prefer:

• SVG for architecture and sequence diagrams
• consistent title and caption text
• simple text formatting when possible

If a specific SVG renders poorly in the browser, re-export with simpler text settings or keep a PNG fallback only for that case.

Review Standard

A diagram is good enough when:

• a newcomer can understand the story without reading the entire page first
• the boxes and arrows match the actual repo structure
• the diagram clarifies something that prose alone makes harder
• the SVG is readable in both desktop and laptop browser widths