# superdesigndev/superdesign architecture

> Architecture diagram of the GitHub repository superdesigndev/superdesign, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/superdesigndev/superdesign
- Repository: https://github.com/superdesigndev/superdesign

## Overview

##### Project Type and Purpose
- This is a VS Code (and Cursor/Windsurf/Claude Code) extension, combining:
– A backend “extension host” component (Node/TypeScript)
– A frontend “webview” component (React + TypeScript)
– Integration with external AI services (Claude Code, Cursor, OpenAI, etc.)
- Purpose: let users generate UI mockups, components, and wireframes from prompts directly inside the IDE.

##### File Structure
- Top-level “src” directory is split into:
– extension.ts: entry point that initializes the VS Code extension
– providers/: e.g. chatSidebarProvider.ts registers the sidebar webview
– services/: encapsulate external-API calls and logging (chatMessageService, claudeCodeService, customAgentService, logger)
– templates/: HTML/JS template for the webview
– tools/: “agent” helper tools representing file-system operations (bash, ls, grep, read/write)
– types/: shared TypeScript interfaces
– webview/: React application (App.tsx, components, hooks, styles) that runs inside VS Code’s WebView
- Configuration files (tsconfig.json, eslint.config.mjs), build scripts (esbuild.js), and package manifests.

##### Readme Insights
- The extension stores generated designs in `.superdesign/` locally
- Users interact via a sidebar panel that hosts the webview (Canvas, Chat UI, Mode toggles)
- Supports external subscriptions (Cursor, Claude Code)

1. IDE Host / Extension Host
– Responsibilities: activate extension, register sidebar provider, handle commands, forward messages
– Key file: src/extension.ts
2. Webview Client (React)
– Renders UI: chat interface, canvas preview, theme tools
– Key files: src/webview/index.tsx, App.tsx, components/…
3. Template Engine
– webviewTemplate.ts injects HTML + bundled React into the webview
4. Agent Services
– chatMessageService handles prompt formatting
– claudeCodeService, customAgentService call external AI APIs
5. Local Storage
– `.superdesign/` folder for saving generated mockups
6. Tools Layer
– Helper scripts (bash-tool, read-tool, write-tool) the agent can invoke
7. External AI Platforms
– Cursor, Claude Code, OpenAI, Windsurf endpoints

##### Relationships & Data Flows
- User types a prompt in the Webview → React UI
- React UI posts a message to the Extension Host (via `vscode.postMessage`)
- Extension Host receives message → dispatches to appropriate Service
- Service formats prompt, calls external AI API → receives design data
- Extension Host saves to local storage (`.superdesign/`) and forwards result back to Webview
- Webview updates Canvas and Component previews

##### Architectural Patterns & Principles
- MVC-style separation:
– Model: Services + storage
– View: Webview React components
– Controller: Extension host routing messages
- Message-passing between host and webview
- Dependency inversion: Services abstract external API details
- Plugin architecture: VS Code activation hooks and providers

##### Technologies & Frameworks
- Node.js + TypeScript
- VS Code Extension API
- esbuild for bundling
- React + Hooks in the webview
- External AI APIs (Claude Code, OpenAI, Cursor)
- Local file I/O for design persistence

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph "VS Code Extension Context"
        EH["Extension Host"]:::host
        SP["Sidebar Provider"]:::host
        WE["Webview Template Engine"]:::host
        subgraph "Services & Tools"
            CMS["Chat Message Service"]:::service
            CCS["Claude Code Service"]:::service
            CAS["Custom Agent Service"]:::service
            LOG["Logging Service"]:::service
            TOOLS["Tools Layer"]:::service
        end
        TYPES["Shared Types"]:::service
    end

    subgraph "Webview Context"
        WC["Webview Client"]:::web
        APP["App.tsx"]:::web
        COMPS["UI Components"]:::web
        HOOKS["Hooks"]:::web
        UTILS["Utilities"]:::web
    end

    STOR["Local Storage (.superdesign/)"]:::storage

    subgraph "External AI Platforms"
        CURSOR["Cursor"]:::external
        CLAUDE["Claude Code"]:::external
        OPENAI["OpenAI"]:::external
        WINDS["Windsurf"]:::external
    end

    WC -->|"PromptRequest"| EH
    EH -->|"registers Sidebar"| SP
    SP -->|"provides Webview"| WE
    EH -->|"routes Prompt"| CMS
    CMS -->|"FormattedPrompt"| CAS
    CAS -->|"API Request"| CLAUDE
    CAS -->|"API Request"| CURSOR
    CAS -->|"API Request"| OPENAI
    CAS -->|"API Request"| WINDS
    CLAUDE -->|"DesignPayload.json"| CAS
    CURSOR -->|"DesignPayload.json"| CAS
    OPENAI -->|"DesignPayload.json"| CAS
    WINDS -->|"DesignPayload.json"| CAS
    CAS -->|"DesignPayload"| EH
    EH -->|"Write File"| STOR
    STOR -->|"Read/Write"| EH
    EH -->|"ResponseData"| WC
    WC -->|"Display Design"| APP
    EH -->|"logs events"| LOG

    click EH "https://github.com/superdesigndev/superdesign/blob/main/src/extension.ts"
    click SP "https://github.com/superdesigndev/superdesign/blob/main/src/providers/chatSidebarProvider.ts"
    click WE "https://github.com/superdesigndev/superdesign/blob/main/src/templates/webviewTemplate.ts"
    click WC "https://github.com/superdesigndev/superdesign/blob/main/src/webview/index.tsx"
    click APP "https://github.com/superdesigndev/superdesign/blob/main/src/webview/App.tsx"
    click COMPS "https://github.com/superdesigndev/superdesign/tree/main/src/webview/components/"
    click HOOKS "https://github.com/superdesigndev/superdesign/tree/main/src/webview/hooks/"
    click UTILS "https://github.com/superdesigndev/superdesign/tree/main/src/webview/utils/"
    click CMS "https://github.com/superdesigndev/superdesign/blob/main/src/services/chatMessageService.ts"
    click CCS "https://github.com/superdesigndev/superdesign/blob/main/src/services/claudeCodeService.ts"
    click CAS "https://github.com/superdesigndev/superdesign/blob/main/src/services/customAgentService.ts"
    click LOG "https://github.com/superdesigndev/superdesign/blob/main/src/services/logger.ts"
    click TOOLS "https://github.com/superdesigndev/superdesign/tree/main/src/tools/"
    click TYPES "https://github.com/superdesigndev/superdesign/tree/main/src/types/"

    classDef host fill:#add8e6,stroke:#333,stroke-width:1px
    classDef service fill:#90ee90,stroke:#333,stroke-width:1px
    classDef storage fill:#90ee90,stroke:#333,stroke-width:1px
    classDef web fill:#ffa500,stroke:#333,stroke-width:1px
    classDef external fill:#d3d3d3,stroke:#333,stroke-width:1px
```
