Smokestack
Where humans and AI agents co-author design docs

Collaborative system design

Design architectures visually. Simulate them with real math. Then let AI agents co-author the design document — capacity plans, failure modes, and all. Humans and agents, building together.

Start BuildingBrowse CommunityBrowse Skills

Humans design. Agents document. Together.

A collaborative workflow where you and AI agents build validated, documented system architectures.

Design

Drag components onto a canvas — or let an agent scaffold the architecture from a prompt.

Simulate

Push traffic through your design. Queueing theory validates every component under load.

Break

Inject failures. Kill nodes, spike traffic 10x. Find where it falls apart before it ships.

Document

AI agents co-author your design doc — capacity plans, failure modes, and mitigations from real simulation data.

Collaborate

Share designs with your team or the community. Fork, remix, and review — humans and agents side by side.

Popular Architectures

Explore real system designs. Fork them, tweak the parameters, and run simulations.

REST API

Programmable infrastructure design

Create, simulate, and document system architectures from any script, CI pipeline, or AI agent. Full OpenAPI 3.1 spec included.

Create a design
curl -X POST https://smokestack.dev/api/v1/designs \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Payment Service",
    "nodes": [
      { "id": "gw", "type": "apiGateway",
        "position": { "x": 0, "y": 0 } },
      { "id": "svc", "type": "service",
        "position": { "x": 300, "y": 0 } },
      { "id": "db", "type": "database",
        "position": { "x": 600, "y": 0 } }
    ],
    "edges": [
      { "source": "gw", "target": "svc" },
      { "source": "svc", "target": "db" }
    ]
  }'
Run a simulation
curl -X POST https://smokestack.dev/api/v1/\
  designs/{id}/simulate \
  -H "Authorization: Bearer sk_live_..." \
  -d '{
    "durationSeconds": 120,
    "baseRps": 5000,
    "chaosEvents": [
      { "type": "kill_node",
        "targetId": "svc",
        "atSecond": 60 }
    ]
  }'

# Returns: throughput, latency percentiles,
# utilization per component, bottleneck
# analysis, and mitigation suggestions

API Key Auth

Generate keys from the dashboard. SHA-256 hashed, prefix-visible, revocable.

OpenAPI 3.1

Full spec at /api/v1/openapi.json. Import into Postman, generate SDKs, or feed to an LLM.

Full CRUD + Fork

List, create, update, delete, and fork designs. Every response includes a shareable URL.

MCP Server

Your agent's architecture toolkit

Connect Claude, Cursor, or any MCP-compatible agent directly to Smokestack. Agents design architectures, run simulations, and co-author design docs alongside you.

claude_desktop_config.json
{
  "mcpServers": {
    "smokestack": {
      "command": "npx",
      "args": ["@smokestackdev/mcp"],
      "env": {
        "SMOKESTACK_API_KEY": "sk_live_..."
      }
    }
  }
}
list_designs

Browse all your designs

create_design

Build a new architecture

update_design

Modify nodes and edges

run_simulation

Simulate traffic & chaos

generate_doc

Architecture documentation

fork_design

Fork any public design

list_components

Browse component catalog

create_scenario

Save simulation configs

get_design

Fetch design details

delete_design

Clean up designs

list_scenarios

Saved test scenarios

explore_public

Community gallery

list_skills

Browse agent skills

get_skill

Skill details & config

Simulation Engine

Real math, not hand-waving

Every simulation is backed by actual queueing theory and scalability models. Not a toy — the same math used in capacity planning at scale.

M/M/c Queueing

Multi-server queueing model calculates wait times, queue depths, and utilization based on arrival rates and service capacity. Erlang-C formula for accurate prediction.

Universal Scalability Law

Models contention and coherency penalties as you add replicas. Predicts the point of diminishing returns and retrograde throughput.

Little's Law

L = λW — the fundamental theorem linking concurrency, throughput, and latency. Used to validate simulation output and detect impossible configurations.

Chaos Engineering

Kill nodes, spike traffic, add latency, sever connections. Inject failures at specific time offsets and watch cascading effects propagate through your architecture.

Human + Agent Collaboration

Design docs, co-authored

You bring the architecture vision. AI agents bring the documentation rigor. Collaborate in real-time — humans and agents working on the same design doc simultaneously.

Agent-Authored Sections

Agents write capacity plans, failure mode analyses, and scaling recommendations directly from your validated simulation data. You review and refine.

Real-Time Collaboration

Yjs-powered collaborative editing. See teammates' cursors and agent edits in real-time. No conflicts, no merging. Humans and agents, same doc.

Living Documents

Embedded interactive architecture diagrams, simulation results, and code blocks. Docs stay in sync with the design — never stale, always tested.

Design docs that write themselves

Build the architecture. Simulate it. Let agents co-author the design doc from what actually works. Free to start.

Get Started FreeBrowse Skills