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.
{
"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": "s1", "to": "m1", "type": "injects" },
{ "from": "f1", "to": "s1", "type": "implements" },
{ "from": "e1", "to": "s1", "type": "injects" }
]
}
AI coding agents (Antigravity, Claude Code, Cursor, Windsurf) use these standalone CLI tools to validate syntax and auto-assign Dagre layout coordinates:
node .agents/skills/arch-design/scripts/validate.js architecture.arch
node .agents/skills/arch-design/scripts/layout.js architecture.arch
curl -s https://anujanthwal-dotcom.github.io/Arch-Design/llms.txt
Press Ctrl+Shift+P / Cmd+Shift+P → Select "Arch: Install Agent Skill"
💡 Click any card above to simulate Focus Mode (isolates upstream & downstream dependencies).
Everything you need to turn high-level thoughts into concrete, verifiable low-level architectures.
Organize complex codebases into distinct domain Modules, Services, typed Functions, and External infrastructure nodes.
Click any card to isolate full upstream and downstream call chains with animated glowing data flows.
Strict low-level design rules block illegal imports, circular dependencies, and leaked database references.
Clean, structured architecture blueprints parsed directly by Claude, Gemini, Antigravity, and Cursor.
Topological graph alignment engine auto-calculates non-overlapping coordinates in a single click.
Native badge support and connection points for industry-standard databases, caches, queues, and object storage.
Arch Design adapts its card archetypes, visual badges, and connection guardrails to fit your tech stack's native architectural idioms.
When you set a technology tag on an External Node (e.g. tech: "postgres" or tech: "redis"), Arch Design automatically renders official logos and connection endpoints:
Arch keeps system designs clean by enforcing explicit relationship boundaries.
| Source Node | Target Node | Relationship | Status |
|---|---|---|---|
| Service | Module | Service is injected into parent module boundary (injects) |
✓ Allowed |
| Function | Service | Function implements / provides method to parent service (implements) |
✓ Allowed |
| External | Service | External database, queue, or cache injected into service (injects) |
✓ Allowed |
| External | Module | External infrastructure dependency injected into module (injects) |
✓ Allowed |
| Service | Service | Dependency service injected into consumer service (injects) |
✓ Allowed |
| Module | Module | Submodule is part of / injected into parent module boundary (submodule) |
✓ Allowed |
| Module | Service | Modules encapsulate services; edges point child to parent | ✕ Blocked (Violates LLD) |
| Service | Function | Edges point from child implementer to parent service | ✕ Blocked (Violates LLD) |
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.
Agents inspect .arch files to identify service boundaries, method signatures, parameter types, and database dependencies before touching a single line of code.
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.
Run Arch: Install Agent Skill from the VS Code Command Palette to equip your current project or global agent environment in 1 click.
Complete guides, CLI scripts, prompts, and schema references for developers and AI coding agents.
Equip any AI coding agent with the knowledge to read, understand, validate, and draw .arch diagrams.
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
# 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/templates/skills/arch-design .agents/skills/ cp /tmp/arch/templates/AGENTS.md ./
| 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) |
Standalone Node.js scripts bundled with the skill so agents never make syntax errors or have to guess pixel math.
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.
node .agents/skills/arch-design/scripts/validate.js architecture.arch # Sample output: # ✓ Validation Passed: 'architecture.arch' is schema-compliant. Nodes: 6, Edges: 5
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.
# 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 coding agents and developers can target any of the 14 pre-configured presets by specifying "framework": "<id>" in the root .arch JSON canvas document.
{
"version": 2,
"domain": "frontend",
"framework": "nextjs",
"name": "store-web",
"nodes": [ /* Cards with tier-appropriate types: page, component, store, action */ ],
"edges": [ /* Directional dependency injection edges */ ]
}
| Framework | Preset ID | Category | Curated Card Archetypes | Source Code Mapping |
|---|---|---|---|---|
| Next.js | "nextjs" |
Frontend | Page/Layout, Component (RSC), Store/Hook, Server Action, Schema (Zod), API/DB | app/**/page.tsx, actions/ |
| React SPA | "react" |
Frontend | View/Route, UI Component, Custom Hook, Store (Zustand/Redux), API Client, DTO | src/components/, src/hooks/ |
| Nuxt 3 / Vue | "vue-nuxt" |
Frontend | Page/Route, Vue SFC, Composable, Pinia Store, Nitro Route, API Service | pages/, composables/, server/ |
| NestJS | "nestjs" |
Backend | Nest Module, REST Controller, Injectable Provider, Guard/Pipe, DTO, Database | *.module.ts, *.service.ts |
| Spring Boot | "springboot" |
Backend | RestController, Service, JPA Repository, JPA Entity, DTO/Record, Database/Queue | @RestController, @Service |
| FastAPI | "fastapi" |
Backend | APIRouter, Domain Service, Pydantic Model, ORM Entity, Dependency, Database/Cache | routers/, schemas/, models/ |
| Modular Backend | "backend" |
Backend | Module Boundary, Domain Service, Controller, Typed Function, Model/DTO, Database | src/modules/, src/services/ |
| Android (Compose) | "android" |
Mobile | Screen Composable, ViewModel (StateFlow), UseCase, Repository, Room DAO, Room DB | ui/screens/, viewmodels/ |
| iOS (SwiftUI) | "ios" |
Mobile | SwiftUI View, ViewModel (Observable), Coordinator, Repository, SwiftData Model | Views/, ViewModels/ |
| Flutter | "flutter" |
Mobile | Widget/Screen, BLoC/Provider, Clean UseCase, Repository, Model/Entity, Local DB | lib/screens/, lib/bloc/ |
| Systems (Rust / Tokio) | "systems" |
Systems | Crate/Mod, Struct, Trait, Enum, Function Routine, Driver/FFI | src/lib.rs, crates/ |
| Go (Clean Architecture) | "go-clean" |
Systems | Go Package, HTTP Handler, Usecase, Repository, Go Struct/Model, Driver/DB | internal/usecase/, pkg/ |
| Clean Architecture | "clean-arch" |
Patterns | Domain Entity, UseCase Interactor, Controller/Adapter, Port/Gateway, Presenter, Infra | domain/, usecases/, adapters/ |
| Universal Standard | "universal" |
Patterns | Module, Component, Service, Type Contract, Function, External Store | Language agnostic / arbitrary architecture |
Tested, high-performing prompts to use with Antigravity, Claude Code, Cursor, or Windsurf.
A step-by-step visual guide to designing software architectures and shipping with AI agents in VS Code.
Search for "Arch Design" by Anuj Anthwal in the VS Code Extensions tab (Ctrl+Shift+X / Cmd+Shift+X), then click Install.
code --install-extension AnujAnthwal.arch-for-LLD-design
Launch the visual canvas inside your project in two easy ways:
Arch: New Architecture File..arch or .lld (e.g., architecture.arch) anywhere in your repo.In the top toolbar, click the cascading framework selector (e.g., Web › Next.js). Choose from 14 curated presets:
View all 14 supported framework presets with logos →
Click buttons in the top strip to drop cards onto the infinite canvas:
+ Module, + Service, + Function, + External, or framework-specific components.userId: string), return types, tech stack tags, and implementation file paths.Link caller and target components together using circular connector handles:
Drag from the right handle of the calling component and release onto the left handle of the dependency. Validation prevents illegal cyclic or cross-boundary connections.
Organize complex diagrams and export them directly to AI coding assistants:
Arch: Install Agent Skill, then prompt Antigravity, Cursor, or Claude: "Implement src/ according to architecture.arch".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