Visualizations in design documents (standard, 27 Oct; TD-072)¶
Atul, 27 Oct: visualizations become part of our design documentation. This standard says which picture goes where, in what format, and who keeps it current. It applies to every project's designs (MMDEP, API/MM-Cron, PE, MWMC, MCRM, WPDev).
1. Every design level has its pictures¶
| Design level | Required picture | Format |
|---|---|---|
| Overall design (per component) | C4 context and container views; one data-flow diagram | C4 in architecture/workspace.dsl (drawn on the docs site); data flow in Mermaid flowchart |
| Phase design | Milestone map: what changes, in what order | Mermaid flowchart or gantt |
| Sprint LLD | A diagram of the change whenever more than two parts interact; a stateDiagram for anything with states; an erDiagram for new tables; a sequenceDiagram for a new API call chain |
Mermaid in the LLD's Diagram section |
| Programme | The five-harness framework: harnesses.md | Mermaid |
2. Formats: text first¶
- Mermaid inside the Markdown file is the default. It is a text file in the repository: versioned, reviewable in a PR, and drawn on GitHub and on the docs site. Agents and the harness can edit it.
- C4 model (
architecture/workspace.dsl): the one source for system and container views. A new component goes into the model before the LLD that uses it (the design check enforces this). - Images (PNG/SVG) from Gemini, ChatGPT or Excalidraw are allowed as concept references only. Store them in
docs/architecture/img/(or the project'sdocs/design/img/), named<topic>-concept-<tool>-<date>.png. Label them "concept, not as-built", and redraw in Mermaid anything that becomes design. - Generated HTML or dashboards (for example a report preview) are evidence, not design. Link them from the LLD's test plan.
3. Rules for agents¶
- An LLD with more than two interacting parts has a
## Diagramsection with at least one Mermaid block. (From S2 the design check warns when it's missing; it blocks from S3.) - A diagram shows only what exists or what the design decides. Unverified parts are marked: Mermaid class
unverified(dashed), or "(planned)" in the label. - Keep labels in plain words. No client data, hostnames with credentials, or secrets in any picture.
- When a design changes, its diagram changes in the same PR.
- Images over 2 MB go through the repository only if they are the concept source. Otherwise link them.
4. Review¶
The design review (Claude Design or MMDEP-PM) checks two things: that the picture matches the text, and that the status markings are true.