Diagrams & architecture

Architecture and business-process documentation for SaaS products often needs diagrams without maintaining separate draw.io exports. This PoC uses Mermaid (rendered client-side) plus patterns for workshop boards, Postman, and static downloads (CSV templates).

User journey (flowchart)

flowchart LR
subgraph Public
  A["Marketing / docs home"]
  B["Public guides"]
end
subgraph Authenticated
  C["Keycloak login"]
  D["Platform docs"]
  E["Product docs"]
end
A --> B
B -->|requiresAuth| C
C --> D
D --> E
E -->|missing role| F["ODS upsell"]
E -->|has group| G["Full content"]

Simplified doc access flow (this PoC)

API handshake (sequence)

Short summary: your application obtains a JWT from Keycloak, then calls the Connect API with Authorization: Bearer ….

sequenceDiagram
participant App as "Your app"
participant DIH as "Connect API"
participant IAM as "Keycloak"
App->>IAM: Client credentials / user login
IAM-->>App: Access token (JWT)
App->>DIH: GET /assets (Bearer token)
DIH-->>App: 200 JSON

Typical machine-to-machine and user-delegated access

Deployment sketch (C4-style)

flowchart TB
subgraph K8s["K8s cluster"]
  POD["Docs SSR pod"]
  POD -->|OIDC| KC["Keycloak"]
end
User["Reader browser"] --> POD
Author["GitLab CI"] -->|build image| POD

Docs on Node adapter — aligns with this repository's Docker/K8s target

Workshop diagrams (FigJam / Excalidraw)

For discovery workshops, teams often keep whiteboard artefacts outside git. Link or embed them from Starlight so narrative docs stay the source of truth.

FigJam
Excalidraw

FigJam (Figma) provides an embed URL from Share → Embed. Use a custom WorkshopEmbed wrapper:

import WorkshopEmbed from '@/components/WorkshopEmbed.astro';

<WorkshopEmbed
  title="Connector onboarding workshop"
  src="https://www.figma.com/embed?embed_host=share&url=ENCODED_FIGJAM_BOARD_URL"
  href="https://www.figma.com/board/..."
  caption="FigJam board — updated by product design"
/>

FigJam embed (PoC placeholder)

Paste a share / embed URL from FigJam or Excalidraw in WorkshopEmbed.

Open FigJam

Replace `src` with your board’s embed URL from Share → Embed. PoC shows the link-only pattern until a board URL is configured.

Excalidraw scenes are usually shared as links (.excalidraw JSON or excalidraw.com URLs). Full iframe embeds depend on how the scene is published; many teams use a screenshot + open in Excalidraw pattern for compliance.

Architecture whiteboard (Excalidraw)

Paste a share / embed URL from FigJam or Excalidraw in WorkshopEmbed.

Open Excalidraw

Export PNG/SVG from Excalidraw for versioned docs, or link to a shared scene for workshops.

Production options

Approach	Notes
Link-out	Simplest; no iframe CSP issues
`@excalidraw/excalidraw`	React embed in an Astro island
Exported SVG	Check in to `public/images/diagrams/` for stable renders

Postman & OpenAPI

Pair narrative docs with a Postman collection and the same OpenAPI spec as the API embed page.

Get Postman

Download collection (JSON)

Download OpenAPI (YAML)

Import in Postman: File → Import → select connect-api-poc.postman_collection.json, set collection variables baseUrl and accessToken (JWT from Keycloak).

To publish a Run in Postman button, upload the collection to a Postman workspace and use the share link Postman generates (same JSON file as source of truth in git).

Downloads & CSV templates

Ship templates, sample payloads, and legal PDFs as static files under public/downloads/. Starlight pages link to them with a small DocDownload card (no extra build step).

connect-asset-export-template.csv Column layout for bulk asset metadata import (PoC example). ~0.5 KB connect-api-poc.postman_collection.json Postman collection matching the fictional Connect API spec. ~1 KB connect-api.openapi.yaml OpenAPI 3 contract served to Swagger UI on the API embed page.

Example Markdown-only link (same file):

Download the [CSV import template](/downloads/templates/connect-asset-export-template.csv).

Tool comparison

Tool	Best for
Mermaid in MDX	Flows in git, reviewable diffs
Excalidraw / FigJam	Workshop diagrams, linked or embedded boards
Postman + OpenAPI	Try-it-out collections aligned with reference
Static downloads	CSV templates, SDK zips, sample payloads
PlantUML	Strict UML, via remark plugin
D2 / Structurizr	C4 architecture as code

Next: Embedded API docs.