Archer

Design your software architecture on a whiteboard-style canvas with real technology components (Web app, AWS, Postgres, …), strict connection rules, and structured detail inside every node. The whole canvas is one .arch diagram-as-code file.

Why

Coding agents are only as good as the spec you hand them. Diagrams describe systems well but export as pixels; diagram/ whiteboard tools describe pictures, not systems. An Archer document is a semantic model:

• Strict — arrows can't point at nothing (the UI snaps them back; the validator rejects them with E101), ids must resolve, payloads must parse.
• Deep — a Postgres node carries its actual schema as a validated json/yaml/table payload, and a queue edge carries its message schema the same way; components nest like JSON, and planes group them on the canvas.
• Round-trip — canvas ↔ text with zero loss. Layout lives in a quarantined machine-managed layout block: agents may read it to see the diagram as drawn, never implement it, and write it only when asked to arrange things.
• Readable at a glance — a component can take a shape (a cylinder for a store, a person for a user, a robot for an agent) and an icon, and any component can hold components: it's one box on the canvas, and opening it shows its parts.
• Agent-first — "Copy for agent" emits the canonical document, with its layout and a short guide prepended. Paste it into Claude Code / Cursor and say "build this".

arch "Acme SaaS" v0.2

component web "Web App" @vercel.nextjs {
  shape browser
}

plane backend "Backend" @vercel {
  component api "API" @vercel.functions {
    component checkout "Checkout" {
      icon shopping_cart
    }
    component projects "Projects" {
      icon folders
    }
  }
  component db "Postgres" @supabase.postgres {
    shape cylinder
    schema json ```
    { "users": { "id": "uuid pk", "email": "text unique" } }
    ```
  }
}

api.projects -> db @sql
web -> api @http

Monorepo

package	what
packages/lang	The language: parser, validator (typed error codes), canonical formatter, layered auto-layout, AST transforms, agent-export compiler. Pure TypeScript, no app dependencies.
packages/catalog	Curated component catalog (~350 types: vendor-neutral system-design and AI building blocks — load balancers, rate limiters, queues, LLMs, agents, MCP servers… — plus real technologies) + Phosphor glyphs.
packages/mcp	MCP tools giving agents full human-parity access — projects CRUD, validated writes, custom types, layout control, spec compilation, the docs' worked examples — served by the app at /mcp with OAuth sign-in. See docs/mcp.md.
packages/cli	The archer command (npm: archerctl): check / fmt for .arch files in CI and agent shells, init, login, push / pull, and archer mcp (stdio bridge to the hosted server). See docs/cli.md.
apps/web	Next.js app: React Flow canvas, palette, detail panel, live code pane, drill-down navigation, Convex persistence.

Docs: language spec · MCP server · CLI · repo sync · product spec · roadmap. The site publishes the first three at /language, /docs/mcp (with a tool reference generated from the server) and /docs/cli.

Run it

pnpm install
pnpm --filter @archer/lang test     # 82 language tests

pnpm dev                              # Convex + Next together → http://localhost:3000

# Convex CLI: always through the alias (or from apps/web), never bare at the root
pnpm convex dashboard

Sign-in is GitHub via Clerk. One-time setup:

1. Create a Clerk application, enable GitHub under SSO connections, and add a JWT template named convex.
2. Put NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY and CLERK_SECRET_KEY in apps/web/.env.local (template in .env.example).
3. Point Convex at your Clerk instance: npx convex env set CLERK_JWT_ISSUER_DOMAIN https://<your-slug>.clerk.accounts.dev

Deploying to Convex cloud + Vercel: see docs/deploy.md.

Connect Claude Code (or any MCP client) to your projects — no keys: the agent signs you in with GitHub the first time it connects (MCP OAuth). Locally the app serves the MCP server at http://localhost:3000/mcp:

claude mcp add --transport http archer http://localhost:3000/mcp

The archer CLI signs in the same way (archer login); see docs/cli.md. Connect an agent in the avatar menu shows the commands for the deployment you're on.

Status

v1.1 — the full core loop works: design on the canvas (drag, connect, group on planes, nest and open components, detail panels with validated payloads), watch the .arch file update live, copy code + PNG for an agent — and agents get the same powers over MCP (validated writes, layout-preserving updates, custom types). A document can also be stored in a .arch file in its GitHub repository: agents edit the file alongside the code, the canvas follows the branch, and edits made on the canvas are published back as pull requests (repo sync). Next: real auth, sharing, per-technology payload validation (SQL linting etc.), multi-file documents.