Diagram roadmap — recommended Mermaid by page
Diagram type key
Section titled “Diagram type key”| Code | Type |
|---|---|
| A | ERD (entity relationship) |
| B | Data dictionary (column meaning — overlaps generated DocType tables) |
| C | Data flow (DFD) |
| D | BPMN-style process |
| E | Sequence |
| F | State machine |
| G | System architecture |
| H | Package / module |
| I | Information architecture (sitemap) |
| J | User flow |
Page × recommended diagrams
Section titled “Page × recommended diagrams”| Page / area | Priority | Secondary |
|---|---|---|
| Home | G, I | — |
| Start guide | I, J | G |
| Reading order | H | E |
| Scenario: Billing → Xero, Payroll | C, E | F |
| Platform primer | G | H |
| System context | G | — |
| System overview, Request flow | G, E | C |
| Technology stack | G, H | — |
| Module catalog | H | I |
| Application lifecycle | E, F | C |
| Billing flow | C, E | F |
| Debt, Xero tenant | E, C | A (partial) |
| Integrations (all four) | E, C | A (integration tables) |
| Custom DocTypes, ER diagrams | A, B | C |
| DocType reference (generated) | B | A (summary only) |
| API inventory | E | H |
| Doc events, Schedulers | E, F | C |
| Overrides, Scripts | E | H |
| Flows overview | D, F | C |
| Deployment, Cloudflare Pages, Security | G | — |
| Glossary, How to read | I | — |
Sprint suggestion
Section titled “Sprint suggestion”- G — System context (done as baseline).
- E — deepen on Xero, Billing, Application lifecycle pages.
- A / B — ER diagrams + generated tables.
- I / J — refine Start guide and tutorials.
Related
Section titled “Related”- Feature inventory by category
- Documentation upgrade roadmap — Billing/Xero/Payroll sequence priority and C4-style container follow-ups
Diagram maintenance rules
Section titled “Diagram maintenance rules”| Rule | Rationale |
|---|---|
| Keep diagrams small | Large Mermaid blocks rot quickly when code changes |
| Co-locate | Put diagrams in the same .md as the narrative they explain |
| Version in PR | When behavior changes, update diagrams in the same PR as code when possible |
| Prefer links over duplication | One canonical sequence diagram per flow; link from Flows overview |
New pages since this roadmap
Section titled “New pages since this roadmap”Add rows to the table above when you create:
- Architecture decisions
- Operational runbook
- Environment matrix
- Domain documentation strategy
- Documentation upgrade roadmap
Suggested types: G (context) for ADR index; G/E for runbook procedures.