# pascalx-git/sketchprompt architecture

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

- Interactive diagram: https://gitdiagram.com/pascalx-git/sketchprompt
- Repository: https://github.com/pascalx-git/sketchprompt

## Overview

##### Project type and purpose
- SketchPrompt is an OpenVSX-compatible editor extension (e.g., VS Code, Cursor IDE, Windsurf) that provides a rich sketching canvas inside the editor.
- It consists of two runtime components:
a. A TypeScript-based extension “host” that integrates with the editor’s Extension API (commands, custom editors, file watching).
b. A React-based Webview (built with Vite) hosting TLDraw for in-editor sketching.
- It ships also with a static documentation website and an experimental “canvas-experiments” demo app.

##### File structure
Top-level directories & files:
- src/                → VSCode/OpenVSX extension entry points (extension.ts, SketchPromptCustomEditor.ts)
- media/              → Webview assets & code (sketching-app.tsx, SketchExportService.ts)
- canvas-experiments/ → Standalone React/Vite demo sandbox
- website/            → Static docs site (HTML/CSS/JS, deploy.sh)
- config/build files: vite.config.ts, webpack.config.js, tsconfig.json
- root scripts & docs: package.json, README.md, HELP.md, SECURITY.md, etc.

##### README insights
- Architecture summary:
- Extension (TypeScript)
- Webview (React + TLDraw)
- Build: Vite for webview, TypeScript compiler/webpack for extension
- Core features: auto-save (debounced), file watching (self-trigger suppression), JSON file schema

##### Main components & interactions
1. Editor Host (OpenVSX runtime)
2. SketchPrompt Extension (Node/TypeScript)
3. Webview UI (React + TLDraw in an iframe-like panel)
4. File System (local .sketchprompt files)
5. Build Pipeline (Vite → Webview bundle; tsc/webpack → Extension)
6. Static Website (deploy via deploy.sh)
7. Experimental Demo App (canvas-experiments)
b. Relationships & data flows
- Editor Host loads the Extension
- Extension registers commands & custom editor provider
- On “New Sketch” or “Open .sketchprompt”, Extension spawns Webview
- Webview sends “load sketch” request → Extension reads JSON file → returns data
- User draws in Webview → TLDraw emits change events → Webview posts “save” message
- Extension receives save message → debounced write to FS → backup & recovery logic
- File Watcher in Extension monitors FS changes → self-trigger suppression → Webview reload
- Build Pipeline: npm scripts build Webview bundle (vite) and compile Extension (tsc/webpack)
- Static Website lives separately—deployed via deploy.sh
c. Architectural patterns & principles
- MV(VC) pattern: Extension = controller, Webview = view, FS JSON = model
- Message-passing API between Extension & Webview
- Debounce + deep equality for optimized auto-save
- File watcher with suppression to avoid infinite loops
- Local-first, privacy-by-design, no external cloud dependencies
d. Key technologies & frameworks
- OpenVSX/VSCode Extension API (Node + TypeScript)
- React & react-dom + TLDraw for Webview UI
- Vite for webview bundling
- TypeScript & webpack/tsc for extension build
- JSON schema validation, CSP, path traversal protection

##### Diagramming recommendations
- Use clear labels: “Editor Host”, “SketchPrompt Extension”, “Webview (React+TLDraw)”, “Local FS”
- Extension ↔ Editor API calls
- Extension ↔ Webview message passing (load/save events)
- Extension ↔ File System read/write and file watcher events
- npm scripts → build outputs
- Blue rectangles for runtime components

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Runtime Components
    subgraph "Runtime Components"
        direction TB
        EditorHost["Editor Host (OpenVSX/VSCode)"]:::runtime
        Extension["SketchPrompt Extension\n(Node/TypeScript)"]:::runtime
        Webview["Webview (React + TLDraw)"]:::runtime
        FS(("Local FS\n(.sketchprompt JSON)")):::storage
    end

    %% Build Pipelines
    subgraph "Build Pipelines (Dev/CI)"
        direction TB
        Scripts["npm Scripts"]:::build
        WP_CompileExt["Compile Extension\n(webpack/tsc)"]:::build
        Vite_Bundle["Bundle Webview\n(Vite)"]:::build
        Schema["Language & Schema\n(sketchprompt-language-configuration.json)"]:::build
        Scripts -.-> WP_CompileExt
        Scripts -.-> Vite_Bundle
        WP_CompileExt -->|"extension dist"| Extension
        Vite_Bundle -->|"webview bundle"| Webview
    end

    %% Documentation & Demos
    subgraph "Documentation & Demos"
        direction TB
        Site["Static Website"]:::static
        Demo["Canvas Experiments\n(React/Vite)"]:::static
    end

    %% Runtime Interactions
    EditorHost -->|"load extension"| Extension
    EditorHost -->|"API calls"| Extension
    Extension -->|"spawn webview"| Webview
    Webview -->|"load sketch request"| Extension
    Extension -->|"read JSON"| FS
    Extension -->|"return data"| Webview
    Webview -->|"TLDraw change events"| Webview
    Webview -->|"post save message"| Extension
    Extension -->|"debounced write"| FS
    FS -->|"file change events"| Extension
    Extension -->|"reload webview"| Webview

    %% Click Events for Extension/Host
    click Extension "https://github.com/pascalx-git/sketchprompt/blob/main/src/extension.ts"
    click Extension "https://github.com/pascalx-git/sketchprompt/blob/main/src/SketchPromptCustomEditor.ts"
    click Extension "https://github.com/pascalx-git/sketchprompt/blob/main/tsconfig.json"
    click Extension "https://github.com/pascalx-git/sketchprompt/blob/main/webpack.config.js"
    click Extension "https://github.com/pascalx-git/sketchprompt/blob/main/package.json"

    %% Click Events for Webview
    click Webview "https://github.com/pascalx-git/sketchprompt/blob/main/media/src/sketching-app.tsx"
    click Webview "https://github.com/pascalx-git/sketchprompt/blob/main/media/src/SketchExportService.ts"
    click Webview "https://github.com/pascalx-git/sketchprompt/blob/main/vite.config.ts"

    %% Click Events for Build
    click WP_CompileExt "https://github.com/pascalx-git/sketchprompt/blob/main/webpack.config.js"
    click WP_CompileExt "https://github.com/pascalx-git/sketchprompt/blob/main/tsconfig.json"
    click WP_CompileExt "https://github.com/pascalx-git/sketchprompt/blob/main/package.json"
    click Vite_Bundle "https://github.com/pascalx-git/sketchprompt/blob/main/vite.config.ts"
    click Vite_Bundle "https://github.com/pascalx-git/sketchprompt/blob/main/package.json"
    click Schema "https://github.com/pascalx-git/sketchprompt/blob/main/sketchprompt-language-configuration.json"

    %% Click Events for Documentation & Demos
    click Site "https://github.com/pascalx-git/sketchprompt/blob/main/website/index.html"
    click Site "https://github.com/pascalx-git/sketchprompt/blob/main/website/script.js"
    click Site "https://github.com/pascalx-git/sketchprompt/blob/main/website/styles.css"
    click Site "https://github.com/pascalx-git/sketchprompt/blob/main/website/deploy.sh"
    click Demo "https://github.com/pascalx-git/sketchprompt/blob/main/canvas-experiments/src/App.tsx"
    click Demo "https://github.com/pascalx-git/sketchprompt/blob/main/canvas-experiments/src/main.tsx"
    click Demo "https://github.com/pascalx-git/sketchprompt/blob/main/canvas-experiments/vite.config.ts"
    click Demo "https://github.com/pascalx-git/sketchprompt/blob/main/canvas-experiments/package.json"

    %% Styles
    classDef runtime fill:#D0E8FF,stroke:#000,stroke-width:1px
    classDef storage fill:#DFFFD0,stroke:#000,stroke-width:1px
    classDef build fill:#FFE5B4,stroke:#000,stroke-width:1px
    classDef static fill:#E0E0E0,stroke:#000,stroke-width:1px
```
