sd-architect

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.

1. Ask or infer what components the system has
2. Write the JSON following the format in reference.md
3. 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

1. Write architecture.json — see reference.md for the format and examples.md for patterns
2. Render: run the render command above
3. Read the downloaded PNG to verify the layout
4. Edit the JSON and re-render until the diagram looks right
5. 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