Blueprint Diagram Routing

Canonical routing rule for structured visual documentation output. Established 2026-04-21 on Blueprint's onboarding day. Pattern follows showcase-website-routing.md.

The Rule

All structured diagram output routes through Blueprint.

Any agent that needs a diagram block — Mermaid, React Flow JSON, Cytoscape.js HTML — requests it from Blueprint and embeds or publishes the result. No agent produces diagram syntax inline as a side effect of prose work.

Diagram Type	Format	Consumer	Surface
Process diagrams	Mermaid flowchart	Architect, wiki, operating procedures	Embedded in .md deliverables
Journey maps	Mermaid sequence/journey	Sage briefs, /journey docs, portal	Embedded in .md + portal sections
User story maps	/build Canvas JSON (WhiteboardNodeData[] + WhiteboardEdge[])	/build Whiteboard layer	apps/build/ canvas state
ERDs	Mermaid erDiagram	/build Data Model Designer, docs	Embedded in .md specs
System architecture	Mermaid C4/flowchart	docs/architecture/, wiki	Embedded in .md
Dependency graphs	Mermaid graph + Cytoscape.js HTML	Hone manifests, QMS process register	Hone validation artifacts
Org charts	Cytoscape.js HTML	/mnt/d/Leadership/assessments/	Standalone .html files

What Blueprint Does NOT Own

Work	Owner	Why
Raster illustrations, image assets	Pixel	Binary asset generation
Slide decks	Presentation-generator	ConceptPresentation layout system
Canvas page publishing to portal	Showcase	Showcase owns the build/deploy pipeline
Portal section rendering	Pavilion	Portal experience decisions
Markdown prose around diagrams	Architect, Scrivener	Blueprint returns diagram blocks, not wrapping prose
/build canvas app UI code	Squire (maintenance), Showcase (new features)	Canvas app implementation

Delegation Chains

Architect → Blueprint

Trigger: Architect is building a document that requires a diagram section.

Architect: "I need a Mermaid ERD for {client}'s HubSpot object model"
  → spawn blueprint (subagent_type: "blueprint")
  → pass: object list, association pairs, context from spec
  → Blueprint returns: Mermaid erDiagram block
  → Architect embeds block in document

Architect does NOT generate Mermaid inline. Blueprint is the diagram specialist.

Hone → Blueprint

Trigger: Hone needs a visual dependency graph for a cross-layer audit or validation artifact.

Hone: "Render this dependency map as Cytoscape.js HTML"
  → spawn blueprint (subagent_type: "blueprint")
  → pass: node list, edge list, layout hint (e.g., "hierarchical left-to-right")
  → Blueprint returns: standalone Cytoscape.js HTML file
  → Hone saves to audit artifacts path

Showcase → Blueprint

Trigger: Showcase is building an interactive canvas experience that needs diagram content.

Showcase: "I need React Flow JSON for {client}'s journey map"
  → spawn blueprint (subagent_type: "blueprint")
  → pass: stage list, persona, touchpoints, context
  → Blueprint returns: React Flow node/edge JSON (or Mermaid for static embed)
  → Showcase embeds in portal section or `/build` canvas layer

CRITICAL: Blueprint's React Flow JSON output for /build must conform to the /build app's canvas type vocabulary at apps/build/src/lib/types.ts. The relevant types are:

• Whiteboard layer: WhiteboardNodeData[] + WhiteboardEdge[]
• Journey layer: JourneyMap (with JourneyStage[])
• Process layer: WorkflowNode[] + WorkflowEdge[]

Blueprint does NOT invent new node/edge shapes. It maps content to existing type variants.

/build → Blueprint

Trigger: /build Data Model Designer needs per-layer schematic content (e.g., a user story map for the Whiteboard layer, or a journey map for the Journey layer).

/build command or Foundry: "Generate user story map for Paragon stories → Whiteboard layer"
  → spawn blueprint (subagent_type: "blueprint")
  → pass: story list, epic groupings, persona
  → Blueprint returns: WhiteboardNodeData[] + WhiteboardEdge[] JSON
  → Consumer writes to /build canvas state

Commands That Route Through Blueprint

These commands produce diagram output. In the current state most generate Mermaid inline. The routing rule is: diagram sections come from Blueprint, not the command orchestrator inline.

Command	Diagram Type	When Blueprint Is Needed
/journey	Journey map (Mermaid + optional React Flow)	Any --diagram flag or portal-embedded journey
/spec	ERDs + architecture diagrams	Spec includes data model section
/ucv	System architecture + data flow	UCV microsite includes architecture view
/walkthrough	Process diagrams	Walkthrough includes process flow sections
/capability-report	System context diagrams	Report includes architecture visualization
/decision-record	Context diagram (C4)	ADR includes architecture context
/process-documentation	Process flowcharts	Operating procedure includes step diagrams

Note: Commands do not need to be rewritten today. This routing rule is the reference that command authors consult when adding diagram sections. As commands are migrated to delegation manifests, Blueprint rows are added to the Team table.

Detection Triggers

Stop immediately if you catch any of these:

If you're doing this...	You're misrouting because...	Fix
Writing Mermaid inline inside a deliverable document	Architect should delegate to Blueprint	Spawn blueprint, embed result
Generating WhiteboardNodeData[] JSON inside a command	Command orchestrators don't produce canvas content	Spawn blueprint
An agent generating Cytoscape.js HTML directly	Blueprint is the Cytoscape specialist	Spawn blueprint
"I'll just add a quick diagram" in an operating procedure	Quick diagrams accumulate as unreviewed technical debt	Spawn blueprint

How to Invoke Blueprint in a Team Table

| blueprint | Blueprint | **sonnet** | Generate {diagram type} for {context} — return {Mermaid block / JSON} | {What to pass: objects, stages, relationships, etc.} |

Blueprint always returns raw diagram output (no prose wrapper). The calling agent embeds it.

Substrate Consistency Rules

/build Canvas (apps/build/src/lib/types.ts)

Blueprint's output for /build MUST use the types defined in apps/build/src/lib/types.ts. Key constraints:

• Whiteboard nodes: WhiteboardNodeType = 'sticky' | 'text' | 'shape' | 'container'
• Shape variants: ShapeType = 'start-end' | 'process' | 'decision' | 'data' | 'document' | ... (see full list in types.ts)
• Journey stages: JourneyStage with objectIds[] references
• Process nodes: WorkflowNode with type = 'trigger' | 'action' | 'branch' | 'delay' | 'end'
• Layer assignment: Every node carries a layer: LayerType field — Blueprint must assign the correct layer

Do NOT invent new node types. Map to the closest existing ShapeType or WhiteboardNodeType.

SubwayMapV3 (apps/portal/src/sections/SubwayMapV3/types.ts)

SubwayMapV3 uses its own type system (SubwayMapConfig, PlannedObject, PlannedPipeline, etc.) and is NOT React Flow. Blueprint does not produce SubwayMapV3 output. SubwayMapV3 content is configured via the HubSpot Company subway_map_config property and managed by Pavilion + Ledger.

If a visual representation of a client's HubSpot architecture is needed outside SubwayMapV3 (e.g., in a spec document or wiki page), Blueprint produces a Mermaid ERD — not SubwayMapV3 JSON.

Per-BU Caller Notes

BU Leader	Top Use Cases	Expected Output
Marquee	Show production workflow diagrams, episode pipeline flowcharts, media platform architecture	Mermaid flowchart (process diagrams for operating procedures)
Provost	Course curriculum journey maps, learning path flowcharts, cohort progression diagrams	Mermaid journey + flowchart
Trellis	Collective member journey map, practitioner engagement flow, community structure org chart	Mermaid journey + Cytoscape.js HTML (org chart)
Foundry	App architecture diagrams, product dependency graphs, API flow diagrams	Mermaid C4 + flowchart
Exchange	Commerce transaction flow, subscription lifecycle diagram, payment process flowchart	Mermaid flowchart (sequence + stateDiagram)
Relay	Client engagement journey maps, engagement stage flowcharts, team capacity org chart	Mermaid journey + Cytoscape.js HTML

All BU leaders: when your brief or operating procedure requires a visual, do not generate diagrams inline. Pass the content specification to Blueprint and embed the returned block.