Arch Design is live • 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.

architecture.arch
Web › Next.js ▾
AuthService ● 2 in ● 1 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
⋮⋮ users-db
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": "s1", "to": "m1", "type": "injects" },
    { "from": "f1", "to": "s1", "type": "implements" },
    { "from": "e1", "to": "s1", "type": "injects" }
  ]
}

⚡ 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
Agent Documentation & Context (llms.txt) Open llms.txt →
curl -s https://anujanthwal-dotcom.github.io/Arch-Design/llms.txt
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 complex codebases into distinct domain Modules, Services, typed Functions, and External infrastructure nodes.

Module Boundary Service Coordinator Typed Function External Store

Focus Mode Tracing

Click any card to isolate full upstream and downstream call chains with animated glowing data flows.

1 Upstream • 2 Downstream

Enforced Guardrails

Strict low-level design rules block illegal imports, circular dependencies, and leaked database references.

AI Coding Agent Ready

Clean, structured architecture blueprints parsed directly by Claude, Gemini, Antigravity, and Cursor.

Dagre Auto-Layout

Topological graph alignment engine auto-calculates non-overlapping coordinates in a single click.

Built-in Infrastructure Recognition

Native badge support and connection points for industry-standard databases, caches, queues, and object storage.

PostgreSQL Redis MongoDB Apache Kafka RabbitMQ MySQL AWS S3 ClickHouse
14 Curated Presets • Multi-Domain Support

Supported Frameworks & Stacks

Arch Design adapts its card archetypes, visual badges, and connection guardrails to fit your tech stack's native architectural idioms.

Next.js Frontend
App Router, React Server Components (RSC), Server Actions, and Zustand stores.
Provided Card Archetypes
Page / Layout Component (RSC) Store / Hook Server Action Schema (Zod) API / Database
React SPA Frontend
Client-side routing (Vite / CRA), UI views, custom hooks, and Redux/Zustand state.
Provided Card Archetypes
View / Route UI Component Custom Hook Store (Zustand) API Client Type / DTO
Nuxt 3 / Vue Frontend
Nuxt 3 pages, Vue SFC components, Pinia reactive stores, and Nitro server endpoints.
Provided Card Archetypes
Page / Route Vue SFC Composable Pinia Store Nitro Route API Service
NestJS Backend
Enterprise TypeScript with modular dependency injection, guards, interceptors, and DTOs.
Provided Card Archetypes
Nest Module REST Controller Injectable Service Guard / Pipe DTO / Schema Database / ORM
Spring Boot Backend
Enterprise Java & Kotlin with Spring Web MVC, JPA repositories, and domain entities.
Provided Card Archetypes
RestController Service JPA Repository JPA Entity DTO / Record Database / Queue
FastAPI / Python Backend
High-performance async Python with APIRouters, Pydantic schemas, and ORM entities.
Provided Card Archetypes
APIRouter Domain Service Pydantic Model ORM Entity Dependency Database / Cache
Modular Backend Backend
Generic modular monoliths, distributed microservices, controllers, and service layers.
Provided Card Archetypes
Module Boundary Domain Service Controller Function Routine Model / DTO Database
Android (Compose) Mobile
Compose UI screens, StateFlow ViewModels, Clean domain UseCases, and Room DB.
Provided Card Archetypes
Screen Composable ViewModel (StateFlow) UseCase Repository DAO / Entity Room DB
iOS (SwiftUI) Mobile
SwiftUI views, Observable ViewModels, navigation Coordinators, and SwiftData.
Provided Card Archetypes
SwiftUI View ViewModel (Observable) Coordinator Repository SwiftData Model SwiftData Store
Flutter Mobile
Cross-platform Dart apps with Widget trees, BLoC / Cubit state, and Clean UseCases.
Provided Card Archetypes
Widget / Screen BLoC / Provider UseCase Repository Model / Entity Local DB / API
Rust / Tokio Systems
Systems programming with Crates, Structs, Traits, Tokio async runtimes, and FFI.
Provided Card Archetypes
Crate / Mod Struct Trait Enum Function Routine Driver / FFI
Go (Clean Arch) Systems
Idiomatic Go packages, HTTP Handlers, Usecases, Repositories, and Structs.
Provided Card Archetypes
Go Package HTTP Handler Usecase Repository Go Struct Driver / DB
Clean Architecture Pattern
Strict onion layers: Entities, UseCases, Adapters, Ports & Gateways, and UI Presenters.
Provided Card Archetypes
Domain Entity UseCase Interactor Adapter / Controller Port / Gateway Presenter / UI Infra Driver
Universal Standard Pattern
Standard architectural primitives for any language, tech stack, or custom system.
Provided Card Archetypes
Module Boundary UI Component Service Logic Type Contract Function Routine External Store

Recognized Infrastructure & Storage Badges

External Nodes • Automatic Brand Badging

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:

PostgreSQL
Redis
MongoDB
MySQL
Apache Kafka
RabbitMQ
AWS S3 / MinIO
SQLite / Room
SwiftData / CoreData
GraphQL
WebSockets
REST APIs / Network

Architecture Connection Rules

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)
⚡ 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/templates/skills/arch-design .agents/skills/
cp /tmp/arch/templates/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

📦 Supported Framework Presets & Schema Reference

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.

Schema Configuration Example

architecture.arch (Root JSON)
{
  "version": 2,
  "domain": "frontend",
  "framework": "nextjs",
  "name": "store-web",
  "nodes": [ /* Cards with tier-appropriate types: page, component, store, action */ ],
  "edges": [ /* Directional dependency injection edges */ ]
}

Complete Framework Reference Matrix

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

💬 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."
User Manual • Workflow Guide

How to Use Arch Design

A step-by-step visual guide to designing software architectures and shipping with AI agents in VS Code.

01 Installation

Install from Marketplace

Search for "Arch Design" by Anuj Anthwal in the VS Code Extensions tab (Ctrl+Shift+X / Cmd+Shift+X), then click Install.

Terminal / CLI 1-Click
code --install-extension AnujAnthwal.arch-for-LLD-design
100% offline & private. No cloud accounts, sign-ups, or telemetry required.
02 Workspace

Create or Open an Architecture

Launch the visual canvas inside your project in two easy ways:

  • Command Palette: Press Ctrl+Shift+P / Cmd+Shift+P and run Arch: New Architecture File.
  • File Explorer: Create any file ending in .arch or .lld (e.g., architecture.arch) anywhere in your repo.
Arch Design opens automatically as a native custom visual editor tab.
03 Frameworks

Select Framework Architecture

In the top toolbar, click the cascading framework selector (e.g., Web › Next.js). Choose from 14 curated presets:

Next.js NestJS React SPA FastAPI Spring Boot Flutter Go Clean Rust Tokio

View all 14 supported framework presets with logos →

The toolbar dynamically adapts with archetypes specific to your chosen stack.
04 Canvas

Add & Detail Architecture Cards

Click buttons in the top strip to drop cards onto the infinite canvas:

  • Archetypes: + Module, + Service, + Function, + External, or framework-specific components.
  • Card Details: Click inputs on cards to specify parameters (e.g. userId: string), return types, tech stack tags, and implementation file paths.
Cards auto-save your edits continuously to disk without manual save prompts.
05 Wiring

Connect Dependencies with Handles

Link caller and target components together using circular connector handles:

Caller / Consumer ● Right Handle
────────➔
● Left Handle Dependency / Target

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.

06 Layout & AI

Auto-Layout, Focus & AI Shipping

Organize complex diagrams and export them directly to AI coding assistants:

  • Auto Layout: Click Auto Layout in the top toolbar to neatly arrange cards into clean Dagre hierarchical columns.
  • Focus Mode: Turn on Focus Mode (or hover any card) to highlight connected execution paths and dim background clutter.
  • AI Coding Agents: Run Ctrl+Shift+P → Arch: Install Agent Skill, then prompt Antigravity, Cursor, or Claude: "Implement src/ according to architecture.arch".

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