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

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

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).

Keep specs in sync

Store OpenAPI under public/specs/ and export the Postman collection from that spec in CI so docs, Swagger UI, and Postman never diverge.

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).

CSV connect-asset-export-template.csv Column layout for bulk asset metadata import (PoC example). ~0.5 KB ↓ Postman connect-api-poc.postman_collection.json Postman collection matching the fictional Connect API spec. ~1 KB ↓ YAML 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).

Larger artefacts

For files over ~10 MB, prefer object storage (S3, Azure Blob) with versioned URLs documented in frontmatter — git LFS is an alternative for teams that want binaries beside docs.

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

Accessibility

Prefer a short prose summary before each diagram so screen-reader users get the story even when SVG is decorative.

Next: Embedded API docs.