Diagram Generator

/diagrams generates visual architecture diagrams from topology data without Visio or draw.io. The pipeline:

topology_nodes + edges + zones
        │
        ▼ scope filter (env / type / id / only_managed)
        │
        ▼ layout engine (hierarchical | force | concentric | zone)
        │
        ▼ styling (env-color per node, encryption-color per edge)
        │
        ▼ optional: Ollama AI analysis → summary + risks
        │
        ▼ React Flow canvas (drag-to-edit, save with version history)
        │
        ▼ export PNG | SVG | PDF | Mermaid

Layout Algorithms

Algorithm	When to Use
hierarchical	N-tier architecture, request flow, firewall → server chains. Coffman-Graham BFS, deterministic sort per layer
force	Mesh networks, microservices, organic topologies. Fruchterman-Reingold, 300 iterations, critical edges drawn 2× stronger
concentric	Blast radius visualization, dependency analysis. Focus node in center, rings 1/6/12/18/24
zone	Compliance documentation, network segmentation. Swimlanes per environment in fixed order (internet → dmz → prod → …)

Diagram Types

Type	Filtering
`architecture`	all nodes (default)
`network_flow`	all nodes, edges shown with direction
`dependency`	3-hop BFS from `focus_node_id`
`compliance_zone`	swimlanes per environment, with group rectangles
`blast_radius`	concentric layout from focus node
`data_flow`	all nodes with traffic_profile=continuous = animated

Templates

5 built-in patterns ready to clone:

3-Tier Web Application — Internet → Firewall → LB → Web Servers → DB
Microservices — API Gateway with 4 backend services + DB
Hub & Spoke Network — central hub with 4 branch locations via IPsec
Zero Trust Architecture — Identity Provider + IAP + apps + SIEM
DR/Backup Setup — Production + DR replica + offsite S3 + monitoring

POST /api/v1/diagrams/from-template/:id clones a template as new diagram.

AI Analysis (Ollama)

With include_ai: true, the generator makes one Ollama call with the full node + edge list plus statistics (unencrypted edges, critical edges, compliance gaps). The LLM returns:

{
  "summary": "2-3 sentence summary of the architecture",
  "risks": [
    { "severity": "high", "description": "…", "remediation": "…" }
  ]
}

Timeout 60 sec, model llama3.1:8b, runs locally in same Docker stack (no external AI provider). On LLM response parse error, the system falls back to raw text as summary.

Export

Format	How
PNG	client-side via `html-to-image`, 2× pixelRatio for retina quality
SVG	client-side via `html-to-image`’s `toSvg`
PDF	PNG embed in `jsPDF` on landscape 1920×1080
Mermaid	server-side via `/api/v1/topology/export/mermaid`
Sharing	public read-only link via `POST /api/v1/diagrams/:id/share` — 32-char URL-safe token, no expiry, tenant_id stripped from response

API

Method	Path
`GET /api/v1/diagrams`	list diagrams + node/edge counts
`POST /api/v1/diagrams/generate`	layout + style + optional auto_save
`GET /api/v1/diagrams/templates`	built-in + tenant templates
`POST /api/v1/diagrams/from-template/:id`	clone template
`GET /api/v1/diagrams/:id` · `PUT` · `DELETE`	CRUD with version history on PUT
`POST /api/v1/diagrams/:id/share` · `unshare`	public link toggle
`GET /api/v1/diagrams/share/:token`	public (no-auth) read-only

Version History

Each PUT /diagrams/:id snapshot the previous version to diagram_versions with change_summary. No UI to see diff’s (on roadmap), but data is there for forensic recovery.

Limitations

No real-time collaboration — multiple editors overwrite each other’s changes. Work per person, use snapshots as synchronization points.
No draw.io XML export — Mermaid is available; draw.io can import Mermaid.
Per-node AI annotations are not yet available — only tenant-level summary + risks.
Crossing minimization — hierarchical layout does no Sugiyama edge-crossing optimization. For diagrams with 50+ nodes, we recommend the zone or force layout.