name

reactflow-architecture-diagrams

description

Delivers narrative interactive architecture diagrams using React, TypeScript, Tailwind, and @xyflow/react (React Flow): node and edge patterns, optional Cloudflare orange shell grouping, routing, and verification. Use when adding or editing React Flow diagram components (Diagram.tsx suffix convention), files under components/diagrams, xyflow edges, animated canvas traffic, or when the user asks for a React Flow architecture diagram alongside documentation.

React Flow architecture diagrams

Canonical rule

Follow rules/815-reactflow-diagrams.mdc for do/don't lists, file globs, and edge semantics. This skill is the playbook; the rule is the contract.

When to use Mermaid vs React Flow

Mermaid (see rules/800-markdown.mdc and skills/documentation-standards): static diagrams in Markdown, ADRs, GitHub-rendered docs.
React Flow: interactive or animated canvases, custom nodes (logos, multi-line cards), and legend + diagram product pages.

Playbook: add a new diagram to an existing SPA

Pick a reference diagram in the same app (or copy patterns from 815) and reduce scope; keep one story per canvas.
Implement buildNodesAndEdges() (or equivalent) returning { nodes, edges }. Keep nodeTypes and edgeTypes at module scope with memo()-wrapped components.
Add a route page: title, scope (what one request or one flow shows), optional static reference image, How to read bullets that map colors and line styles to meaning, then <YourDiagram />.
Wire the router and home or index links; update README routes and assets tables when paths or figures change.
Run lint and production build from the app directory.

Playbook: Cloudflare-scoped traffic

Add a parent shell node (cfShell or your name) with fixed width/height and overflow: 'visible'.
Nest child nodes with parentId + extent: 'parent'; convert world coordinates to parent-relative positions.
Use opaque inner cards for text-heavy nodes sitting on the orange frame (see 815).

Playbook: identity and edge cases

JWKS / metadata fetch is not the same as OIDC login. If both appear, use dashed edges and distinct colors for issuance vs verification, and say so in page copy.

Verification

Do not skip lint and build (or tsc -b) after graph or handle changes; broken Handle ids fail at runtime.

React Flow architecture diagrams

Canonical rule

Follow rules/815-reactflow-diagrams.mdc for do/don't lists, file globs, and edge semantics. This skill is the playbook; the rule is the contract.

When to use Mermaid vs React Flow

Mermaid (see rules/800-markdown.mdc and skills/documentation-standards): static diagrams in Markdown, ADRs, GitHub-rendered docs.

React Flow: interactive or animated canvases, custom nodes (logos, multi-line cards), and legend + diagram product pages.

Playbook: add a new diagram to an existing SPA

Pick a reference diagram in the same app (or copy patterns from 815) and reduce scope; keep one story per canvas.

Implement buildNodesAndEdges() (or equivalent) returning { nodes, edges }. Keep nodeTypes and edgeTypes at module scope with memo()-wrapped components.

Add a route page: title, scope (what one request or one flow shows), optional static reference image, How to read bullets that map colors and line styles to meaning, then <YourDiagram />.

Wire the router and home or index links; update README routes and assets tables when paths or figures change.

Run lint and production build from the app directory.

Playbook: Cloudflare-scoped traffic

Add a parent shell node (cfShell or your name) with fixed width/height and overflow: 'visible'.

Nest child nodes with parentId + extent: 'parent'; convert world coordinates to parent-relative positions.

Use opaque inner cards for text-heavy nodes sitting on the orange frame (see 815).

Playbook: identity and edge cases

JWKS / metadata fetch is not the same as OIDC login. If both appear, use dashed edges and distinct colors for issuance vs verification, and say so in page copy.

Verification

Do not skip lint and build (or tsc -b) after graph or handle changes; broken Handle ids fail at runtime.