VS Code Extension • AI Agent Ready

Design Software Architecture Visually.
Built for Humans & AI Agents.

Arch Design lets you map modules, services, functions, and infrastructure dependencies directly in VS Code. Saved as clean JSON that developers love and AI coding agents can implement faithfully.

Install from Marketplace Star on GitHub
Quick Install: ext install AnujAnthwal.arch-for-LLD-design
architecture.arch
AuthService ● 1 in ● 2 out
⋮⋮ MODULE Authentication
User authentication domain & session tokens boundary.
Scope login, register, JWT issuance
⋮⋮ SERVICE AuthService
Core service coordinating credentials and crypto validation.
Type Reference services/AuthService
Dependencies UserStore, CryptoEngine
⋮⋮ FUNCTION verifyToken
Decodes signature and validates Bearer token claims.
Parameter token: string (Bearer JWT)
Returns TokenPayload: claims
⋮⋮ EXTERNAL PostgreSQL
postgres : 5432
Primary persistent relational store for user records.
{
  "version": 2,
  "name": "auth-system",
  "nodes": [
    {
      "id": "m1",
      "type": "module",
      "label": "Authentication",
      "description": "User auth & session tokens"
    },
    {
      "id": "s1",
      "type": "service",
      "label": "AuthService"
    },
    {
      "id": "f1",
      "type": "function",
      "label": "verifyToken",
      "parameters": [{ "name": "token", "type": "string" }]
    },
    {
      "id": "e1",
      "type": "external",
      "label": "PostgreSQL",
      "tech": "postgres"
    }
  ],
  "edges": [
    { "from": "m1", "to": "s1", "type": "contains" },
    { "from": "s1", "to": "f1", "type": "contains" },
    { "from": "s1", "to": "e1", "type": "uses" }
  ]
}

⚡ Agent Skill Quick Reference

View Full Documentation →

AI coding agents (Antigravity, Claude Code, Cursor, Windsurf) use these standalone CLI tools to validate syntax and auto-assign Dagre layout coordinates:

CLI Validator (Syntax & Architecture Rules) 
node .agents/skills/arch-design/scripts/validate.js architecture.arch
CLI Auto-Layouter (Calculates Clean Coordinates) 
node .agents/skills/arch-design/scripts/layout.js architecture.arch
VS Code 1-Click Installation 
Press Ctrl+Shift+P / Cmd+Shift+P → Select "Arch: Install Agent Skill"

💡 Click any card above to simulate Focus Mode (isolates upstream & downstream dependencies).

Engineered for Clean Software Design

Everything you need to turn high-level thoughts into concrete, verifiable low-level architectures.

Structured 4-Tier Hierarchy

Organize systems cleanly with domain Modules, Services, typed Functions, and External infrastructure nodes.

Focus Mode Tracing

Click any card to highlight its full upstream and downstream path with animated flows while dimming unrelated cards.

Enforced Guardrails

Built-in connection rules prevent invalid architecture shortcuts (e.g. functions directly importing modules or external databases driving business logic).

AI Coding Agent Ready

Direct `.arch` JSON specification ready for LLMs (Claude, GPT, Gemini) to parse and generate accurate code scaffolding.

Dagre Auto-Layout

Instant node alignment and hierarchy organization with one click on the toolbar layout engine.

Infrastructure Tech Badges

Pre-packaged logos and recognition for PostgreSQL, Redis, MongoDB, MySQL, Kafka, RabbitMQ, S3, and more.

Architecture Connection Rules

Arch keeps system designs clean by enforcing explicit relationship boundaries.

Source Node Target Node Relationship Status
Module Service Module encapsulates service ✓ Allowed
Service Function Service contains and executes function ✓ Allowed
Service External Service connects to database, queue, or cache ✓ Allowed
Module External Module depends on external dependency ✓ Allowed
Function Module Function referencing parent module ✕ Blocked (Violates LLD)
⚡ Built for Modern AI Coding Agents

Empower AI Agents to Read & Draw Diagrams

Arch Design includes an open Agent Skill specification. Your AI assistants can inspect system boundaries before writing code, and automatically generate schema-valid .arch diagrams on demand.

Google Antigravity Claude Code Cursor (Composer) Windsurf (Cascade) Cline / Aider

1. Understand Before Coding

Agents inspect .arch files to identify service boundaries, method signatures, parameter types, and database dependencies before touching a single line of code.

2. Draw Diagrams on Demand

Simply prompt your agent: "Create an architecture diagram for our new order processing workflow with Kafka and Redis." The agent outputs a valid .arch file instantly.

3. 1-Click Workspace Setup

Run Arch: Install Agent Skill from the VS Code Command Palette to equip your current project or global agent environment in 1 click.

agent-workflow.sh
# AI Agent validates schema and connection rules
$ node .agents/skills/arch-design/scripts/validate.js architecture.arch
✓ Validation Passed: 'architecture.arch' is schema-compliant. Nodes: 6, Edges: 5

# AI Agent auto-arranges visual positions via Dagre (no manual pixel guessing)
$ node .agents/skills/arch-design/scripts/layout.js architecture.arch
✓ Successfully updated coordinates in: 'architecture.arch'

Documentation & CLI Reference

Complete guides, CLI scripts, prompts, and schema references for developers and AI coding agents.

⚡ Installing the Arch Design Agent Skill

Equip any AI coding agent with the knowledge to read, understand, validate, and draw .arch diagrams.

Method A: VS Code 1-Click Install (Easiest)

VS Code Command Palette 
1. Press Ctrl+Shift+P (or Cmd+Shift+P on macOS)
2. Type and select: Arch: Install Agent Skill
3. Choose scope:
   • "Current Workspace (.agents/skills/arch-design/)" → Best for repositories and teams
   • "Global User Profile (~/.gemini/config/skills/)" → Best across all personal projects

Method B: Manual Installation (Git Clone)

Terminal 
# Copy skill package into your project
git clone https://github.com/Anujanthwal-dotcom/Arch-Design.git /tmp/arch
mkdir -p .agents/skills
cp -r /tmp/arch/.agents/skills/arch-design .agents/skills/
cp /tmp/arch/AGENTS.md ./

Multi-Agent Compatibility Table

Coding Agent How It Discovers the Skill Setup Needed
Google Antigravity / Gemini CLI Scans .agents/skills/ and global config natively Zero setup (Automatic discovery)
Claude Code (Anthropic) Reads root AGENTS.md & CLAUDE.md Pointer in AGENTS.md (Included)
Cursor (Composer / Agent) Reads .cursor/rules/ & .cursorrules Pointer in AGENTS.md / rules
Windsurf (Cascade) Reads .windsurfrules & workspace docs Pointer in AGENTS.md (Included)

🛠 CLI Tools for Agents & Developers

Standalone Node.js scripts bundled with the skill so agents never make syntax errors or have to guess pixel math.

1. CLI Architecture Validator

Verifies JSON schema integrity, required attributes, edge definitions, and architectural separation of concerns. Exits with code 0 on success, or code 1 with actionable error descriptions.

Terminal 
node .agents/skills/arch-design/scripts/validate.js architecture.arch

# Sample output:
# ✓ Validation Passed: 'architecture.arch' is schema-compliant. Nodes: 6, Edges: 5

2. CLI Dagre Auto-Layouter

Automatically assigns non-overlapping (x, y) visual coordinates using Dagre topological graph ranking. AI agents can generate nodes with pos: { x: 0, y: 0 } and run this command to lay them out cleanly.

Terminal 
# In-place auto-layout:
node .agents/skills/arch-design/scripts/layout.js architecture.arch

# Or output to a new file:
node .agents/skills/arch-design/scripts/layout.js architecture.arch ./output.arch

💬 AI Agent Prompting Cheatsheet

Tested, high-performing prompts to use with Antigravity, Claude Code, Cursor, or Windsurf.

1. Implement Code from an Architecture Diagram
"Inspect our architecture diagram in architecture.arch. Implement the service and functions specified in the canvas, strictly respecting parameter types, return signatures, and external database connections."
2. Generate an Architecture Diagram for a New Feature
"Use the Arch Design skill to create a visual architecture diagram user-auth.arch for our user authentication microservice. Include a UserModule, AuthService, verifyToken function, and PostgreSQL external store. Run layout.js and validate.js when finished."
3. Audit Codebase for Architecture Compliance
"Compare our implementation in src/ against architecture.arch. Identify any services calling unauthorized databases or functions bypassing domain boundaries according to our Low-Level Design rules."

📋 JSON Schema v2 Reference

Detailed schema structure for .arch visual canvas files.

Node Type Key Fields Description
module id, label, description, properties[] Top-level domain boundary or package.
service id, label, typeRef, properties[] Business logic service class or controller.
function id, label, parameters[], returns[] Routines with typed inputs, outputs, and descriptions.
external id, label, tech Infrastructure: postgres, mysql, redis, mongodb, kafka, s3, rabbitmq.

Start in 60 Seconds

No separate browser tabs or external SaaS logins required.

01

Install Extension

Search for "Arch Design" in the VS Code Extensions marketplace or run ext install AnujAnthwal.arch-for-LLD-design.

02

Create .arch File

Press Ctrl+Shift+P / Cmd+Shift+P and run Arch: New Architecture File, or create any file ending with .arch.

03

Design & Implement

Drag nodes, define parameters and return types, auto-arrange with Dagre layout, and feed directly to AI coding agents.

Bring Clarity to Your Codebase

Never lose track of your system dependencies or architectural boundaries again.

Get Arch Design for VS Code

Support Open Source with a GitHub Star

Arch Design is 100% free and open-source under the MIT license. If this tool saves you design time, clarifies system boundaries, or powers your AI coding agents, leaving a star on GitHub means the world and helps other engineers discover it!

Star on GitHub