stackmapstackmap
Install

DocsDiagram kinds

Architecture

Components and what they call: services, stores and the infrastructure between them.

Use it when the edges are calls and dependencies. Draw each edge from the initiator to what it calls, even when it only reads; queues are the exception, from producer to queue to consumer. Groups mark the boundaries a reader should see: tiers, trust zones, clusters.

An example

The skill’s own example, web-app.architecture.json, laid out by stackmap.

file:///…/.stackmap/web-app/diagram.html
web-app.architecture.json142 lines
{  "kind": "architecture",  "title": "Bookshop",  "subtitle": "Web storefront and order pipeline",  "direction": "DOWN",  "groups": [    { "id": "edge", "label": "Edge" },    { "id": "app", "label": "App tier" },    { "id": "data", "label": "Data tier" }  ],  "nodes": [    {      "id": "web",      "type": "client",      "card": {        "title": "Storefront",        "subtitle": "Next.js",        "brand": "nextdotjs"      }    },    {      "id": "cdn",      "type": "gateway",      "group": "edge",      "card": {        "title": "CDN",        "subtitle": "Cloudflare",        "brand": "cloudflare"      }    },    {      "id": "api",      "type": "service",      "group": "app",      "card": {        "title": "shop-api",        "subtitle": "REST API · Node.js",        "brand": "nodedotjs",        "rows": [          { "label": "Instances", "value": "3" },          { "label": "Port", "value": ":8080", "mono": true }        ],        "footer": {          "left": { "text": "eu-west-1", "icon": "region" },          "right": { "text": "HTTPS", "icon": "secure" }        }      },      "evidence": [        {          "file": "services/api/src/server.ts",          "line": 12,          "note": "Express app and routes"        }      ]    },    {      "id": "worker",      "type": "service",      "group": "app",      "card": { "title": "order-worker", "subtitle": "Fulfilment jobs" }    },    {      "id": "jobs",      "type": "queue",      "group": "app",      "card": {        "title": "jobs",        "subtitle": "RabbitMQ",        "brand": "rabbitmq"      }    },    {      "id": "db",      "type": "database",      "group": "data",      "card": {        "title": "Orders DB",        "subtitle": "PostgreSQL",        "brand": "postgresql",        "stats": [          { "value": "1", "label": "Primary" },          { "value": "2", "label": "Replicas" }        ],        "statsNote": "Streaming replication"      }    },    {      "id": "cache",      "type": "cache",      "group": "data",      "card": {        "title": "Sessions",        "subtitle": "Redis",        "brand": "redis"      }    },    {      "id": "stripe",      "type": "external",      "card": {        "title": "Stripe",        "subtitle": "Payments API",        "brand": "stripe"      }    }  ],  "edges": [    { "id": "web-cdn", "from": "web", "to": "cdn", "label": "HTTPS" },    { "id": "cdn-api", "from": "cdn", "to": "api" },    { "id": "api-db", "from": "api", "to": "db" },    { "id": "api-cache", "from": "api", "to": "cache" },    {      "id": "api-jobs",      "from": "api",      "to": "jobs",      "kind": "async",      "label": "enqueue"    },    {      "id": "jobs-worker",      "from": "jobs",      "to": "worker",      "kind": "async"    },    { "id": "worker-db", "from": "worker", "to": "db" },    { "id": "api-stripe", "from": "api", "to": "stripe" }  ],  "views": [    {      "id": "checkout",      "label": "Checkout path",      "caption": "What a purchase touches",      "nodes": ["web", "cdn", "api", "stripe", "db"]    },    {      "id": "state",      "label": "State",      "caption": "Where data lives",      "nodes": ["db", "cache", "jobs"]    }  ]}
Point at a node in the JSON, or at its card, to find the other.

Its parts

  • Nine node types

    The type sets the colour, never the brand.

  • Groups

    Tiers, trust zones and clusters, nested with parent.

  • Connections

    Plain calls, async events, and tones for the main path.

  • Views

    Named focus sets, one tab each.

Rules

From the authoring contract the skill gives your agent. stackmap validate enforces the hard ones and names the fix.

  • Draw each edge from the initiator to what it calls or uses: api → db even when the api only reads. Queues and streams are the exception, producer → queue → consumer.
  • "kind": "async" for queues, events, fire-and-forget and callbacks (dashed); "kind": "return" for a reply or a roll back (dotted).
  • A tone marks the few edges a reader must tell apart: main for the happy path, security for a trust crossing, error for a failure path. Leave the rest untoned.
  • Groups are boundaries a reader should see: tiers, trust zones, VPCs, clusters. Nest them with parent; a group with one node is usually noise.
  • "direction": "DOWN" for tiered or grouped systems and anything past about five stages; RIGHT, the default, reads as a request path.
  • Keep one edge per direction between two nodes, and fold both relationships into one label.

Node types

TypeUse it for
ClientBrowsers, mobile apps, CLIs, SDKs: anything a user drives
GatewayLoad balancers, API gateways, CDNs, edge routers, ingress
ServiceYour own processes: APIs, workers, functions, jobs
DatabaseStores that are the system of record
CacheRedis and Memcached-style caches, session stores
QueueBrokers, streams, topics, task queues
StorageObject, blob and file stores, data lakes
ExternalThird-party APIs and SaaS you don’t run
SecurityAuth providers, IAM, secrets managers, WAFs

Ask for one

Make an architecture diagram of this repository, backed by evidence from the code.

Your agent picks the kind that answers the question; naming it is the surest way to get it.

Examples

See architecture examples in the gallery