dendryform

Declarative software architecture diagrams — beautiful, dark-themed, with a simple schema

Named for the 23 dendriform models of tree architecture (Halle & Oldeman, 1970), because every system has a branching pattern worth revealing.

What It Does

dendryform takes a declarative YAML description of a software system — nodes, edges, containment, tiers — and renders it as a beautiful, dark-themed architecture diagram in HTML, SVG, or PNG.

click for full-size

Quick Example

diagram:
  title:
    text: "My API"
    accent: "My API"
  subtitle: "Two-tier service architecture"
  theme: dark

layers:
  - tier:
      id: clients
      label: "Clients"
      nodes:
        - id: web
          kind: person
          color: blue
          icon: "◇"
          title: "Web App"
          description: "React frontend"
          tech: ["TypeScript"]
  - connector:
      style: line
      label: "HTTPS"
  - tier:
      id: services
      label: "Services"
      nodes:
        - id: api
          kind: system
          color: green
          icon: "◈"
          title: "API Server"
          description: "REST endpoints"
          tech: ["Rust", "Axum"]
        - id: db
          kind: infrastructure
          color: amber
          icon: "◯"
          title: "PostgreSQL"
          description: "Primary store"
          tech: ["RDS"]

edges:
  - from: web
    to: api
    kind: uses
    label: "requests"
  - from: api
    to: db
    kind: reads

legend:
  - color: blue
    label: "Clients"
  - color: green
    label: "Services"
  - color: amber
    label: "Data"

Usage

1 — Generate an architecture.yaml with Claude Code

The fastest way to diagram an existing codebase is to let an AI read the schema and your source, then write the YAML for you. Point Claude Code at the bundled schema reference:

Read assets/schema/DIAGRAM-YAML-SCHEMA.md, then analyse the source code
in src/ and generate an architecture.yaml file that captures the system
architecture using the dendryform schema.

The schema document (assets/schema/DIAGRAM-YAML-SCHEMA.md) is written specifically for AI assistants — it covers every field, all valid values, and worked examples.

2 — Render to SVG or PNG

Once you have an architecture.yaml, render it with the CLI:

# PNG — format inferred from the output extension
dendryform render architecture.yaml -o diagram.png

# SVG
dendryform render architecture.yaml -o diagram.svg

# HTML (interactive)
dendryform render architecture.yaml -o diagram.html

# Explicit format flag
dendryform render architecture.yaml -f png -o diagram.png

# Retina PNG (2× scale)
dendryform render architecture.yaml -o diagram.png --scale 2.0

Run dendryform --help or dendryform render --help for all options including --theme and --width.

Workspace Structure

dendryform/
├── Cargo.toml                  # Workspace root
├── crates/
│   ├── dendryform-core/        # Schema types, validation, theme, layout plan
│   ├── dendryform-parse/       # YAML + JSON → Diagram IR
│   ├── dendryform-layout/      # Diagram IR → LayoutPlan
│   ├── dendryform-html/        # LayoutPlan → responsive HTML
│   ├── dendryform-svg/         # LayoutPlan → static SVG
│   ├── dendryform-png/         # SVG → PNG (resvg wrapper)
│   ├── dendryform-ascii/       # LayoutPlan → ASCII art (planned)
│   ├── dendryform-export/      # Lossy exporters: Structurizr DSL, JSON, Mermaid (planned)
│   └── dendryform-cli/         # CLI binary
├── assets/
│   └── schema/                 # DIAGRAM-YAML-SCHEMA.md — AI-readable schema reference
├── examples/                   # Example diagram YAML files and rendered outputs
└── tests/                      # Integration / snapshot tests

License

Licensed under either of Apache License, Version 2.0 or MIT License at your option.