name	sd-architect
description	Create and share software architecture diagrams — write JSON, render via browser, share URLs
argument-hint	[create\|render\|share\|open] [file]
allowed-tools	Bash, Read, Write, Edit

You create software architecture diagrams by writing architecture.json files and rendering them via the sd-architect web app at https://sd.ftl2.com/.

Commands

`sd-architect create [file]`

Write an architecture.json based on the user's description. Default file: architecture.json in the current directory.

Ask or infer what components the system has
Write the JSON following the format in reference.md
Render it (see below) and verify the result

`sd-architect render <file>`

Render a diagram to PNG via the browser. This opens the diagram at sd.ftl2.com with auto-render, which downloads a PNG after 2 seconds.

SKILL_DIR="$(dirname "$(readlink -f ~/.claude/skills/sd-architect/SKILL.md)")"
python3 "$SKILL_DIR/scripts/sd_architect_url.py" <file> --render

The PNG downloads to the system default downloads directory (usually ~/Downloads/). The filename is sd-architect-<timestamp>.png. After the PNG downloads, read it to verify the layout is correct. Iterate if needed.

If no display is available (SSH, containers), the script prints a warning — copy the URL and open it manually.

`sd-architect share <file>`

Print a shareable URL that encodes the diagram directly in the URL fragment.

SKILL_DIR="$(dirname "$(readlink -f ~/.claude/skills/sd-architect/SKILL.md)")"
python3 "$SKILL_DIR/scripts/sd_architect_url.py" <file>

`sd-architect open <file>`

Open a diagram in the browser for interactive editing (no auto-render).

SKILL_DIR="$(dirname "$(readlink -f ~/.claude/skills/sd-architect/SKILL.md)")"
python3 "$SKILL_DIR/scripts/sd_architect_url.py" <file> --open

Workflow

Write architecture.json — see reference.md for the format and examples.md for patterns
Render: run the render command above
Read the downloaded PNG to verify the layout
Edit the JSON and re-render until the diagram looks right
Share the URL or commit the JSON

Writing the JSON

The format is compact and human-readable:

{
  "components": [
    {"name": "api", "type": "service", "technology": "FastAPI", "position": [0, 0]}
  ],
  "connections": [
    {"from": "api_out", "to": "db_query", "label": "SQL"}
  ],
  "view": {"translate_x": 960, "translate_y": 540, "scale": 1.0, "theme": "dark"}
}

Key rules:

Port names follow the pattern <component_name>_<port_suffix> (e.g., api_out, db_query)
Leave ~400px between component centers horizontally, ~250px vertically
Flow reads left-to-right
See reference.md for all component types, ports, and available logos
See examples.md for complete working diagrams

{ "components": [ {"name": "api", "type": "service", "technology": "FastAPI", "position": [0, 0]} ], "connections": [ {"from": "api_out", "to": "db_query", "label": "SQL"} ], "view": {"translate_x": 960, "translate_y": 540, "scale": 1.0, "theme": "dark"} }