stoa

Visualize your app's architecture — right next to Claude Code.

Stoa opens a local web GUI that renders your app's architecture as a schematic diagram, from a single architecture.md file in your repo. No accounts, no sign-up, nothing to connect — point it at a repo and see how the pieces fit.

It ships with a Claude Code skill that can read an existing codebase of any stack and generate that architecture.md for you.

0.0.1 — MVP. The visualizer is the product. Optional verification against live Cloudflare and Supabase resources is included but experimental; see Optional: live verification.

Quick start

npx stoa-plugin@latest .        # open the GUI for the current repo
# or install it globally
npm i -g stoa-plugin && stoa .

A localhost GUI opens with your architecture diagram. That's it.

On first run, Stoa also installs the Stoa Claude Code skill into ~/.claude/skills/stoa (transparent, copied once, opt out with --no-skill).

Getting an architecture.md

The diagram is driven by one fenced ```stoa block in architecture.md (at your repo root or docs/architecture.md). You get one in any of three ways:

1. It already exists — Stoa just renders it.

2. Generate it from your code — ask Claude Code: "generate an architecture.md for this repo." The bundled skill reads your stack — frontend, API services/workers, queues, databases, storage, auth, external services — traces how they're connected, and writes the ```stoa block. Works across stacks.

3. Write your own — the DSL is tiny:

   ```stoa
   frontend:web "Web App"
   web -> service:api "API"
   api -> table:users
   api -> queue:jobs -> worker:mailer
   web -> auth:auth "Auth"
   ```

Starting a brand-new project? Scaffold a ready-to-visualize starter:

npx stoa-plugin init my-app     # then: cd my-app && npm install && stoa .

What you see

The GUI is served on 127.0.0.1 only. The home Blueprint tab renders your architecture.md as a schematic — nodes by type (frontend, service, worker, queue, table, storage, auth, …) wired by the flows you declared. With no live connection, nodes render neutral/gray; the diagram is the point.

Flags: --port <n>, --no-open, --no-skill, --reinstall-skill, --version, --help. Needs Node ≥ 18.18 — no other runtime.

Optional: live verification

Stoa can also check your design against real infrastructure. The Cloudflare and Supabase tabs let you connect with an API token and "Sync" — then Blueprint nodes light up green (built), red (drift), or stay gray (unverified). This is optional and experimental in 0.0.1.

• Tokens are stored in your user config dir (~/.config/stoa/), never in the repo. The Supabase service_role key never leaves the server.
• Syncing writes snapshot files (cloudflare-resources.json, supabase-resources.json, CLOUDFLARE.md, SUPABASE.md) into the repo so Claude can build against your real bindings — add *-resources.json to .gitignore if you don't want account-specific snapshots committed.

Docs

• Getting started — install → run → first diagram.
• Generating architecture.md — how the skill derives a ```stoa block from code.

Contributing / running from source

cd web && npm install && npm run dev   # prints the URL; prefers :3000, falls back if busy

Or with Docker:

docker compose up --build              # http://localhost:3000

Layout:

web/          ← Next.js app (the GUI + its API routes)
release/      ← packaging: bin launcher, assembler, publish manifest
skills/stoa/  ← the Claude Code skill installed on first run
templates/    ← `stoa init` starter(s)

architecture.md is yours / Claude's — Stoa only scaffolds it when missing and never overwrites it. The local API is same-origin-guarded (web/middleware.ts) since it can hold provider tokens.

License: MIT.