# twoguysdev/explorer-for-penpot architecture

> Architecture diagram of the GitHub repository twoguysdev/explorer-for-penpot, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/twoguysdev/explorer-for-penpot
- Repository: https://github.com/twoguysdev/explorer-for-penpot

## Overview

Explorer for Penpot is a VS Code extension for browsing Penpot teams, projects, files, pages, and boards, then previewing a board or page in an editor tab. Users connect to Penpot Cloud or a self-hosted server with a token; the extension validates and stores it, loads the sidebar tree through the Penpot API, and renders SVG previews with optional thumbnail comparison and browser links. The shown source supports the main orchestration and rendering paths; the API and tree excerpts document the read-only data interactions. Localization and broader rendering details are documented capabilities.

Main entry points: [`src/preview.ts`](https://github.com/twoguysdev/explorer-for-penpot/blob/main/src/preview.ts) (Preview panel), [`src/extension.ts`](https://github.com/twoguysdev/explorer-for-penpot/blob/main/src/extension.ts) (Extension commands), [`src/tree.ts`](https://github.com/twoguysdev/explorer-for-penpot/blob/main/src/tree.ts) (Sidebar tree), [`src/api.ts`](https://github.com/twoguysdev/explorer-for-penpot/blob/main/src/api.ts) (Penpot API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_connection["Connection &amp; commands"]
  node_extension["Extension commands<br/>[extension.ts]"]
  node_messages["Errors &amp; warnings<br/>[messages.ts]"]
  node_secretstore[("VS Code secret storage")]
end

subgraph group_browsing["Design browsing"]
  node_tree["Sidebar tree<br/>[tree.ts]"]
  node_api["Penpot API client<br/>[api.ts]"]
end

subgraph group_preview["Preview rendering"]
  node_preview["Preview panel<br/>[preview.ts]"]
  node_renderer["SVG renderer<br/>[render.ts]"]
  node_webview["Preview webview<br/>[preview.ts]"]
end

subgraph group_external["External services"]
  node_penpot["Penpot server"]
  node_browser["Penpot editor"]
  node_googlefonts["Google Fonts"]
end

node_user(("VS Code user"))

node_user -->|"invokes commands"| node_extension
node_extension -->|"reads/writes token"| node_secretstore
node_extension -->|"validates token"| node_api
node_extension -->|"registers and refreshes"| node_tree
node_extension -->|"opens preview"| node_preview
node_extension -->|"opens editor link"| node_browser
node_tree -->|"loads hierarchy and pages"| node_api
node_api -->|"sends authenticated reads"| node_penpot
node_preview -->|"fetches page and assets"| node_api
node_preview -->|"uses cached page data"| node_tree
node_preview -->|"renders objects"| node_renderer
node_renderer -->|"returns SVG and warnings"| node_preview
node_preview -->|"displays preview and thumbnail"| node_webview
node_preview -->|"opens selected design"| node_browser
node_preview -.->|"loads optional fonts"| node_googlefonts
node_tree -->|"formats load errors"| node_messages
node_preview -->|"formats render notices"| node_messages

click node_extension "https://github.com/twoguysdev/explorer-for-penpot/blob/main/src/extension.ts"
click node_messages "https://github.com/twoguysdev/explorer-for-penpot/blob/main/src/messages.ts"
click node_tree "https://github.com/twoguysdev/explorer-for-penpot/blob/main/src/tree.ts"
click node_api "https://github.com/twoguysdev/explorer-for-penpot/blob/main/src/api.ts"
click node_preview "https://github.com/twoguysdev/explorer-for-penpot/blob/main/src/preview.ts"
click node_renderer "https://github.com/twoguysdev/explorer-for-penpot/blob/main/src/render.ts"
click node_webview "https://github.com/twoguysdev/explorer-for-penpot/blob/main/src/preview.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_extension,node_messages,node_secretstore,node_user toneBlue
class node_tree,node_api toneAmber
class node_preview,node_renderer,node_webview toneMint
class node_penpot,node_browser,node_googlefonts toneRose
```

## Components

### Connection & commands

- [Extension commands](https://github.com/twoguysdev/explorer-for-penpot/blob/main/src/extension.ts): `src/extension.ts`
- [Errors & warnings](https://github.com/twoguysdev/explorer-for-penpot/blob/main/src/messages.ts): `src/messages.ts`
- **VS Code secret storage**

### Design browsing

- [Sidebar tree](https://github.com/twoguysdev/explorer-for-penpot/blob/main/src/tree.ts): `src/tree.ts`
- [Penpot API client](https://github.com/twoguysdev/explorer-for-penpot/blob/main/src/api.ts): `src/api.ts`

### Preview rendering

- [Preview panel](https://github.com/twoguysdev/explorer-for-penpot/blob/main/src/preview.ts): `src/preview.ts`
- [SVG renderer](https://github.com/twoguysdev/explorer-for-penpot/blob/main/src/render.ts): `src/render.ts`
- [Preview webview](https://github.com/twoguysdev/explorer-for-penpot/blob/main/src/preview.ts): `src/preview.ts`

### External services

- **Penpot server**
- **Penpot editor**
- **Google Fonts**

### Other components

- **VS Code user**

## Connections

- VS Code user → Extension commands: invokes commands (evidence: `src/extension.ts`)
- Extension commands → VS Code secret storage: reads/writes token (evidence: `src/extension.ts`)
- Extension commands → Penpot API client: validates token (evidence: `src/extension.ts`)
- Extension commands → Sidebar tree: registers and refreshes (evidence: `src/extension.ts`)
- Extension commands → Preview panel: opens preview (evidence: `src/extension.ts`)
- Extension commands → Penpot editor: opens editor link (evidence: `src/extension.ts`)
- Sidebar tree → Penpot API client: loads hierarchy and pages (evidence: `src/tree.ts`)
- Penpot API client → Penpot server: sends authenticated reads (evidence: `src/api.ts`)
- Preview panel → Penpot API client: fetches page and assets (evidence: `src/preview.ts`)
- Preview panel → Sidebar tree: uses cached page data (evidence: `src/preview.ts`)
- Preview panel → SVG renderer: renders objects (evidence: `src/preview.ts`)
- SVG renderer → Preview panel: returns SVG and warnings (evidence: `src/render.ts`)
- Preview panel → Preview webview: displays preview and thumbnail (evidence: `src/preview.ts`)
- Preview panel → Penpot editor: opens selected design (evidence: `src/preview.ts`)
- Preview panel → Google Fonts: loads optional fonts (evidence: `README.md`)
- Sidebar tree → Errors & warnings: formats load errors (evidence: `src/tree.ts`)
- Preview panel → Errors & warnings: formats render notices (evidence: `src/preview.ts`)
