Diagram Backlog designed
The portal serves mixed audiences. Product, CISO, Infra, Ops, Architecture, and app developer readers will not all enter through the same mental model. Diagrams should make the first read easier, not merely make pages prettier.
Diagram System
Use three visual types:
| Type | Use for | Format |
|---|---|---|
| Explainer diagrams | Product shape, capability maps, shared-service model, team paths | Mermaid first; maintained image when layout needs polish |
| Runtime diagrams | Control-plane flow, event flow, terminal path, provisioning, billing, release rings | Mermaid |
| Publication visuals | External/customer-safe overviews, product journey visuals, competitive positioning | Maintained image asset with editable source |
P0 Diagrams
| Diagram | Audience | Format | Portal page | Source docs |
|---|---|---|---|---|
| GPUaaS product capability map | Product, CISO, Architecture | Mermaid now, designed image later | Platform Overview | PRD, Architecture v1 |
| Internal team reader map | All internal teams | Mermaid | Internal Team Onboarding | PRD, Governance Overview |
| User interaction journey | Product, Product UX, Development | Mermaid now, designed image later | User Interactions | UX Journeys |
| Control-plane runtime topology | Architecture, Infra, Ops | Mermaid | System Overview | Architecture v1 |
| Day-2 operations loop | Ops, Infra, CISO | Mermaid | Day-2 Operations | Production Platform Baseline |
| Security and production-readiness posture | CISO, Architecture, Ops | Mermaid now, designed image later | Security & Production Readiness | Security/CD roadmap, gap portfolio |
P1 Diagrams
| Diagram | Audience | Format | Target page |
|---|---|---|---|
| Platform shared services model | Architecture, Development, Infra | Mermaid plus maintained image | Architecture platform foundation |
| Maps, guards, facades sequence | Architecture, Development, agents | Mermaid | Platform foundation / governance |
| Release rings and reserve capacity | Ops, Infra, CISO | Maintained image | Release operations |
| App SDK developer path | App developers, Product | Mermaid now, designed image later | Build on AI Cloud |
| API/event contract lifecycle | Development, Architecture | Mermaid | Developer APIs |
| Governance/change-control flow | Development, Governance, agents | Mermaid | Governance model |
| Competitive positioning map | Product, leadership | Maintained image | Competitive context |
P2 Diagrams
| Diagram | Audience | Format | Target page |
|---|---|---|---|
| Billing and ledger flow | Product, Ops, Development | Mermaid | Billing/storage or system overview |
| Terminal/session security path | CISO, Ops, Development | Mermaid | Security or architecture deep dive |
| Node lifecycle and isolation model | Infra, Ops, CISO | Mermaid plus maintained image | Ops/security deep dive |
| Storage and artifact lifecycle | App developers, Ops | Mermaid | Build on AI Cloud / operators |
| Publication-track filtering model | Content, Product, Security | Mermaid | Publication tracks |
First Reader Map
This diagram should appear on the internal onboarding path once the team agrees on the visual direction.
Image Asset Rules
When a diagram needs to be a maintained image instead of Mermaid:
- Store the rendered file under
packages/docs/static/img/portal/. - Keep editable source beside it when possible.
- Link the page to canonical
source_docs. - Add useful alt text.
- Review the image for publication visibility before customer or public use.
Canonical sources