Visual Engineering

Code ↔ Architecture, Two Ways

Engineer visually: Transform code into architecture diagrams, and architecture into code. A two-way canvas where you think in both dimensions simultaneously.

This isn't documentation - it's engineering with a visual medium. Architecture decisions, code reviews, debugging, onboarding - all happen on a canvas where you can see the whole system.

Works with any MCP-compatible AI tool (Claude Code, Cursor, Windsurf, etc.).

Setup

Prerequisites

1. Circuitry EServer - The bridge that connects your AI tools to Circuitry:

   • macOS: Download from circuitry.dev/download
   • CLI: curl -fsSL https://circuitry.dev/install.sh | sh
   • Docker: docker pull johnwylie/eserver:latest

   See EServer Integration for detailed setup.

2. Circuitry - Open circuitry.dev or run locally

3. An MCP-compatible AI tool - Claude Code, Cursor, Windsurf, or any tool supporting Model Context Protocol

Step 1: Install the MCP Server

# Clone the repository
git clone https://github.com/anthropics/circuitry-mcp-server.git
cd circuitry-mcp-server

# Install and build
npm install && npm run build

Step 2: Configure Your AI Tool

Add the Circuitry MCP server to your tool's configuration:

Claude Code (~/.claude/claude_desktop_config.json):

{
  "mcpServers": {
    "circuitry": {
      "command": "node",
      "args": ["/path/to/circuitry-mcp-server/dist/index.js"],
      "env": {
        "CIRCUITRY_API_KEY": "your-api-key-here"
      }
    }
  }
}

Cursor / Windsurf: Add to your MCP settings with the same configuration.

Step 3: Generate an API Key

1. Open Circuitry → Settings (⚙️) → API Keys
2. Click "Generate New Key"
3. Copy the key into your AI tool's config
4. Restart your AI tool to load the MCP server

Step 4: Connect

1. Start EServer (tray app or eserver start)
2. Open Circuitry in your browser
3. Ask your AI: "Connect to Circuitry" or run circuitry.connect
4. Approve the connection in Circuitry (a dialog will appear)
5. Done - your AI can now engineer visually

Visual Engineering in Practice

1. Code → Architecture: Visualize Your Codebase

Scenario: Understand the login/signup flow in your authentication system.

You: Show me a flowchart of the login/signup flow in my auth module

Your AI reads the code and generates a visual architecture:

[Creates flowchart in Circuitry:]
┌─────────────┐     ┌──────────────┐     ┌─────────────────┐
│ User Input  │────▶│ Validate     │────▶│ Check Existing  │
│             │     │ Email        │     │ User            │
└─────────────┘     └──────────────┘     └────────┬────────┘
                                                   │
                         ┌─────────────────────────┼─────────────────────────┐
                         │ exists                  │                  new    │
                         ▼                         │                         ▼
              ┌──────────────────┐                 │              ┌──────────────────┐
              │ Compare Password │                 │              │ Create Account   │
              └────────┬─────────┘                 │              └────────┬─────────┘
                       │                           │                       │
          ┌────────────┴────────────┐              │                       ▼
          │                         │              │              ┌──────────────────┐
          ▼                         ▼              │              │ Send Verification│
    ┌──────────┐              ┌──────────┐        │              └────────┬─────────┘
    │ Success  │              │ Failure  │        │                       │
    └──────────┘              └──────────┘        │                       ▼
                                                   │              ┌──────────────────┐
                                                   │              │ Success          │
                                                   │              └──────────────────┘

Iterate on the architecture:

You: Add rate limiting before password comparison
AI: [Inserts "Check Rate Limit" diamond node into the flow]

2. Visual Diagnosis: Find Issues in User Journeys

Scenario: Audit your subscription/paywall flow for problems.

You: Create a flowchart of the paywall journey and highlight any issues

Your AI analyzes the code and creates a diagnostic view:

[Flowchart with color-coded issues:]

✓ User visits premium feature → Properly gated (GREEN)
⚠️ Free Trial Start → No expiration check (RED)
⚠️ Payment Failed → No retry logic (RED)
⚠️ Downgrade → Data not migrated (RED)
✓ Upgrade → Properly handled (GREEN)

AI explains the issues:

Found 3 problems in your paywall architecture:

1. **Trial never expires** - No expiration check in trial logic
   📍 src/billing/trial.ts:45

2. **Payment failure is terminal** - No retry or grace period
   📍 src/billing/checkout.ts:112

3. **Downgrade loses data** - Premium content becomes inaccessible
   📍 src/billing/subscription.ts:78

Want me to fix these and update the flowchart?

3. Architecture → Code: Draw First, Implement Second

Scenario: You sketch a validation pipeline, AI implements it.

You: I drew a data validation flow in Circuitry. Implement it in TypeScript.

AI reads your visual architecture:

AI: I see your validation pipeline:
1. Check required fields
2. Validate email format
3. Check password strength
4. Verify age (must be 18+)

[Creates code node in Circuitry:]

export async function validateUserInput(data: UserInput): Promise<ValidationResult> {
  // Step 1: Required fields
  if (!data.email || !data.password || !data.age) {
    return { valid: false, error: 'Missing required fields' }
  }

  // Step 2: Email format
  if (!isValidEmail(data.email)) {
    return { valid: false, error: 'Invalid email format' }
  }

  // Step 3: Password strength
  if (data.password.length < 8) {
    return { valid: false, error: 'Password must be 8+ characters' }
  }

  // Step 4: Age verification
  if (data.age < 18) {
    return { valid: false, error: 'Must be 18 or older' }
  }

  return { valid: true }
}

4. Select → Understand: Point at Anything

Select cells, text, or nodes and ask about them.

Data Analysis (select cells in a sheet):

[Select cells B2:D10 in "Sales Data" sheet]
You: What's the trend here?

AI: Looking at your selection (B2:D10 in "Sales Data"):
- Q1: $45,000
- Q2: $52,000 (+15%)
- Q3: $61,000 (+17%)
- Q4: $58,000 (-5%)

Strong growth Q1-Q3, slight Q4 dip. This correlates with the
marketing budget reduction I see in row 15.

Code Understanding (select lines in a code node):

[Select lines 45-60 in auth.ts]
You: What does this do?

AI: This is `validateToken` (lines 45-60):
1. Extracts JWT from Authorization header
2. Verifies signature with your secret key
3. Checks expiration timestamp
4. Returns decoded user payload

⚠️ Issue: Line 52 catches all errors uniformly. You should
distinguish expired tokens from invalid signatures for better UX.

5. Data Tables for Architecture Planning

Scenario: Map out your API before coding.

You: Create a sheet of our API endpoints with method, path, auth, rate limits

AI creates an editable architecture table:

You: Create User should require auth - security issue

AI: You're right. Updating the architecture:
[Updates sheet: Create User Auth → Yes]
[Creates code node with the fix:]

// Before (security vulnerability)
router.post('/api/users', createUser)

// After (fixed)
router.post('/api/users', requireAuth, createUser)

Key Tools

Flowchart Creation

nodes.createFlowchart({
  nodes: [...],
  edges: [...],
  autoLayout: true  // Auto-arrange with dagre
})

Code Nodes (Bi-directional Sync)

code.create({
  filePath: "/path/to/your/file.ts"  // Syncs changes both ways
})

Sheet Operations

sheet.create({ headers: [...], data: [...] })
sheet.setCells(nodeId, [{ row: 0, col: 1, value: "Updated" }])
sheet.fillRange(nodeId, { col: 2, formula: "=A{row}*B{row}" })

Selection Context

workflow.getSelectionContext()
// Returns: { selectedNodes: [{ nodeId, name, type, cellSelection?, textSelection? }] }

Undo/Redo

workflow.undo()  // Revert last change
workflow.redo()  // Restore undone change

Use Cases

Tips for Effective Visual Engineering

1. Start with the visual - "Show me the architecture" before diving into code

2. Use selection - Point at cells/text/nodes before asking questions for precise context

3. Iterate on the canvas - Modify the flowchart, let AI regenerate code, repeat

4. Combine representations - Sheets for data/config, flowcharts for logic, code for implementation

5. Ask for diagnosis - "Highlight any issues" catches architectural problems visually

6. Think in both directions - Code → Visual for understanding, Visual → Code for design

Troubleshooting

"Connection refused" error

• Make sure EServer is running (eserver status)
• Check the API key is correct in your Claude Code config
• Verify Circuitry is open in your browser

"Permission denied" dialog keeps appearing

• Click "Approve" in Circuitry to allow the MCP connection
• The connection persists until you close Circuitry or disconnect

Changes not appearing in Circuitry

• Refresh your browser (Cmd+R / Ctrl+R)
• Check the browser console for errors
• Restart EServer if connection seems stale

MCP tools not available

• Restart Claude Code after adding the MCP config
• Verify the path to the MCP server is correct
• Check npm run build completed without errors

What's Next?

• EServer Integration - Full setup guide
• Code Generation - Export workflows as production code
• Sheet Node - Excel-like spreadsheets
• Workflow Building - Multi-agent orchestration