GitHub - dziksu/StructSmith: Local-first, MCP-native tool for modelling software architecture. C4-style semantic model, React Flow editor, SQLite, single container — a self-hosted Structurizr alternative your AI client can edit over MCP.

Local-first, MCP-native tool for modelling software architecture. C4-style semantic model, React Flow editor, SQLite, single container — a self-hosted Structurizr alternative your AI client can edi...

Summary

StructSmith is a local-first, self-hosted tool for modeling software architecture with a C4-style semantic model, a React Flow editor, and a built-in MCP server. The semantic model is the source of truth; the React Flow canvas only visualizes it. It ships as a single Docker container with SQLite, is written in TypeScript on Bun, and is MIT licensed.

What it is useful for

• Documenting systems with the C4 model: people, software systems, containers, components, deployment nodes, infrastructure nodes, and custom kinds
• Architecture workshops, presales diagrams, and system design reviews
• Letting an AI client edit the same model you draw, with revision-guarded atomic operations
• Running prompt templates like review_architecture, identify_architecture_risks, identify_unknowns, review_security, and review_scalability against the model
• Importing Mermaid flowchart/graph diagrams as a semantic baseline, and exporting to JSON, Mermaid, PNG, or SVG

How engineers can use it

Run the public image (from the README):

docker run -d --name structsmith \
  -p 127.0.0.1:8090:8080 \
  -v structsmith-data:/data \
  --restart unless-stopped \
  ghcr.io/dziksu/structsmith:latest

Open http://localhost:8090. Workspaces persist in the structsmith-data volume; SQLite is auto-migrated, so no Postgres, Redis, Java, or Python is needed.

Local development with Bun:

git clone https://github.com/dziksu/StructSmith.git structsmith
cd structsmith
bun install --frozen-lockfile
bun run dev

This starts the API on :3000 and the Vite UI on http://localhost:5173.

Connect an AI client. MCP is served at /mcp over Streamable HTTP. Documented commands include:

• Codex: codex mcp add structsmith --url http://localhost:8090/mcp
• Claude Code: claude mcp add --transport http structsmith http://localhost:8090/mcp
• GitHub Copilot CLI: copilot mcp add --transport http structsmith http://localhost:8090/mcp
• VS Code: add .vscode/mcp.json with {"servers": {"structsmith": {"type": "http", "url": "http://localhost:8090/mcp"}}}

Drive changes atomically. The recommended flow is a single call to model_apply_operations with expectedRevision for optimistic concurrency. Each batch runs in one SQLite transaction, takes an automatic snapshot, and either lands fully or not at all. A ref alias on a created entity can be referenced as @alias in later operations in the same batch. The browser subscribes to GET /api/events over SSE, so AI edits appear in the canvas without a refresh.

Documented limitations:

• Defaults (AUTH_MODE=none, HOST=0.0.0.0) target localhost only. The README warns anyone able to reach the port can read and modify workspaces — set AUTH_MODE=token and put TLS in front before exposing it.
• Mermaid import covers flowchart/graph only, capped at 1,000,000 source characters, 2,000 nodes, and 10,000 relationships. The README calls it "a semantic starting point, not a pixel-perfect or lossless round trip": styling, animation, exact shapes, and Markdown formatting are dropped, and sequence, class, ER, state, and C4 Mermaid diagrams are rejected.
• The deprecated SSE MCP transport is not implemented; only Streamable HTTP is.