# haideralsh/prompt-lab architecture

> Architecture diagram of the GitHub repository haideralsh/prompt-lab, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/haideralsh/prompt-lab
- Repository: https://github.com/haideralsh/prompt-lab

## Overview

1. **Overall shape**
   Prompt Lab is a **Tauri desktop application**: a React/Vite frontend in `src/` talks to a Rust backend in `src-tauri/` through Tauri commands and events. The app is cross-platform desktop-first, not a hosted web app.

2. **Frontend shell**
   The UI is centered around `src/app.tsx`, `src/main.tsx`, and the layout components under `src/components/layout/`. The shell includes a header, sidebar, main workspace, footer, and toast system, with the main content organized into panels for directory, Git, instructions, selected files, and web pages.

3. **State and cross-component coordination**
   Global client state lives in `src/state/atoms.ts` and `src/state/initial.ts`, implying an atom-based store for shared app state such as selected directory, file selection, settings, and panel data. Helper utilities like `preserve-selected.ts`, `sort-files-by-token-count.ts`, and `update-window-title.ts` indicate that state is normalized in the UI and reused across multiple panels.

4. **Rust backend boundary**
   The backend is organized under `src-tauri/src/api/`, with each feature exposed as a separate module: `clipboard`, `directory`, `editor`, `git`, `instruction`, `tree`, and `web`. This separation is the key architectural boundary: the UI requests platform-sensitive or filesystem-heavy work from Rust, and Rust returns structured data or emits events back to the UI.

5. **Directory and project loading flow**
   The `directory` API provides directory picking, recent directories, and listing. This is the entry point for a project context: the user selects a workspace, the backend resolves it, and the frontend uses that directory as the root for tree building, Git status, and file selection.

6. **File tree subsystem**
   The `tree` module is one of the core backend subsystems. It includes `index`, `cache`, `select`, `search`, and `render`, showing a pipeline of:
   - indexing a project tree,
   - caching results,
   - searching/filtering nodes,
   - selecting files or nodes,
   - rendering tree data for the UI.
   This is the data backbone for the sidebar file explorer and file-context generation.

7. **Git context subsystem**
   The `git` API provides commands plus `status`, `watch`, `event`, and `tokenize`. This suggests the backend monitors repository state, computes diffs or file statuses, and streams updates to the UI. The Git panel uses those updates to let users include code changes as LLM context, with token counts likely derived from diff content.

8. **Instruction management**
   The `instruction` API and the instruction panel/form components support saving reusable prompt instructions. The frontend has create/edit flows, while the backend stores or validates instruction data. This subsystem is separate from file content and acts as reusable prompt scaffolding.

9. **Web documentation capture**
   The `web` API contains `scrape` and `favicon` functionality. This indicates the app can fetch a webpage, convert it into markdown-like context, and display or save it as prompt material. It is a distinct ingestion path from local files and Git data.

10. **Clipboard and editor integration**
   `clipboard` exposes copy behavior, and `editor` likely opens files in the user’s local editor. These are thin desktop integration layers that let the app hand context out to other tools, rather than keeping everything inside the app.

11. **Token counting as a shared concern**
   Token-related code appears across UI and backend: `src/types/tokens.ts`, `use-token-count-listener.tsx`, Git token listeners, and instruction token counting. Token count is not just a display metric; it influences ordering, selection, and prompt assembly across the app’s main panels.

12. **Selected-file and context composition flow**
   The `selected-files` panel, file-tree selection components, Git panel, web panel, and instruction panel all feed into a context-building workflow. The app appears designed to assemble a final prompt payload from multiple sources: project tree, chosen files, Git diff, saved instructions, and web docs.

13. **Persistence and local app configuration**
   `src/api/settings.ts`, `src/components/sidebar/settings-dialog.tsx`, and `src/store.ts` on the Rust side suggest local persistence for settings and workspace data. The app likely stores recent directories, saved instructions, and UI preferences locally rather than in a remote backend.

14. **Tooling, delivery, and verification**
   The repository uses **pnpm + Vite + React** on the frontend and **Rust/Cargo + Tauri** on the backend. CI is split into `.github/workflows/build.yml` and `test.yml`, and the Rust side has dedicated tests under `src-tauri/tests/`, especially for directory, editor, and tree search APIs.

15. **How to draw the architecture**
   A good diagram should show:
   - a **desktop UI layer** in React,
   - a **Tauri IPC boundary**,
   - backend feature modules for **directory/tree**, **git**, **instructions**, **web scraping**, **clipboard/editor**,
   - and a shared **local state/persistence layer**.
   The central data path is: user picks a directory → backend indexes tree and watches git → UI lets the user select files/instructions/web docs → app composes token-aware context for copying or external use.

Main entry points: [`src/api`](https://github.com/haideralsh/prompt-lab/tree/main/src/api) (IPC API), [`src/components/layout/layout.tsx`](https://github.com/haideralsh/prompt-lab/blob/main/src/components/layout/layout.tsx) (Layout), [`src/components/panels`](https://github.com/haideralsh/prompt-lab/tree/main/src/components/panels) (Panels), [`src-tauri/src/api/tree`](https://github.com/haideralsh/prompt-lab/tree/main/src-tauri/src/api/tree) (Tree API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_app_shell["App shell<br/>React entry<br/>[app.tsx]"]
  node_layout["Layout<br/>UI shell<br/>[layout.tsx]"]
  node_sidebar["Sidebar<br/>Explorer UI<br/>[sidebar.tsx]"]
  node_panels["Panels<br/>Workspace UI"]
  node_state["State atoms<br/>Client state<br/>[atoms.ts]"]
  node_token_ui(("Token UI<br/>Metrics"))
  node_ipc_api["IPC API<br/>Frontend bridge"]
end

subgraph group_backend["Backend"]
  node_directory_api["Directory API<br/>Workspace entry"]
  node_tree_api["Tree API<br/>File tree"]
  node_git_api["Git API<br/>Git context"]
  node_instruction_api["Instruction API<br/>Prompt presets"]
  node_web_api["Web API<br/>Web capture"]
  node_clipboard_api["Clipboard<br/>Desktop integration"]
  node_editor_api["Editor<br/>Desktop integration"]
  node_store[("Local store<br/>Persistence<br/>[store.rs]")]
end

subgraph group_shared["Shared"]
  node_shared_types["Shared types<br/>Data models"]
  node_helpers["Helpers<br/>UI logic"]
  node_context_flow{{"Context build<br/>Workflow"}}
end

node_app_shell -->|"renders"| node_layout
node_layout -->|"contains"| node_sidebar
node_layout -->|"contains"| node_panels
node_layout -->|"shows"| node_token_ui
node_sidebar -->|"reads/writes"| node_state
node_panels -->|"reads/writes"| node_state
node_panels -->|"feeds"| node_context_flow
node_ipc_api -->|"calls"| node_directory_api
node_ipc_api -->|"calls"| node_tree_api
node_ipc_api -->|"calls"| node_git_api
node_ipc_api -->|"calls"| node_instruction_api
node_ipc_api -->|"calls"| node_web_api
node_ipc_api -->|"calls"| node_clipboard_api
node_ipc_api -->|"calls"| node_editor_api
node_directory_api -->|"persists"| node_store
node_tree_api -->|"uses"| node_shared_types
node_git_api -->|"emits counts"| node_token_ui
node_instruction_api -->|"adds"| node_context_flow
node_web_api -->|"adds"| node_context_flow
node_git_api -->|"adds"| node_context_flow
node_tree_api -->|"adds"| node_context_flow
node_helpers -->|"normalizes"| node_state
node_helpers -->|"orders"| node_token_ui

click node_app_shell "https://github.com/haideralsh/prompt-lab/blob/main/src/app.tsx"
click node_layout "https://github.com/haideralsh/prompt-lab/blob/main/src/components/layout/layout.tsx"
click node_sidebar "https://github.com/haideralsh/prompt-lab/blob/main/src/components/sidebar/sidebar.tsx"
click node_panels "https://github.com/haideralsh/prompt-lab/tree/main/src/components/panels"
click node_state "https://github.com/haideralsh/prompt-lab/blob/main/src/state/atoms.ts"
click node_token_ui "https://github.com/haideralsh/prompt-lab/blob/main/src/components/layout/use-token-count-listener.tsx"
click node_ipc_api "https://github.com/haideralsh/prompt-lab/tree/main/src/api"
click node_directory_api "https://github.com/haideralsh/prompt-lab/tree/main/src-tauri/src/api/directory"
click node_tree_api "https://github.com/haideralsh/prompt-lab/tree/main/src-tauri/src/api/tree"
click node_git_api "https://github.com/haideralsh/prompt-lab/tree/main/src-tauri/src/api/git"
click node_instruction_api "https://github.com/haideralsh/prompt-lab/tree/main/src-tauri/src/api/instruction"
click node_web_api "https://github.com/haideralsh/prompt-lab/tree/main/src-tauri/src/api/web"
click node_clipboard_api "https://github.com/haideralsh/prompt-lab/tree/main/src-tauri/src/api/clipboard"
click node_editor_api "https://github.com/haideralsh/prompt-lab/tree/main/src-tauri/src/api/editor"
click node_store "https://github.com/haideralsh/prompt-lab/blob/main/src-tauri/src/store.rs"
click node_shared_types "https://github.com/haideralsh/prompt-lab/tree/main/src/types"
click node_helpers "https://github.com/haideralsh/prompt-lab/tree/main/src/helpers"

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_app_shell,node_layout,node_sidebar,node_panels,node_state,node_token_ui,node_ipc_api toneBlue
class node_directory_api,node_tree_api,node_git_api,node_instruction_api,node_web_api,node_clipboard_api,node_editor_api,node_store toneAmber
class node_shared_types,node_helpers,node_context_flow toneMint
```

## Components

### Frontend

React/Vite desktop UI and client-side state

- [App shell](https://github.com/haideralsh/prompt-lab/blob/main/src/app.tsx): React entry · Bootstraps the desktop UI and routes into the main application layout. · `src/app.tsx`
- [Layout](https://github.com/haideralsh/prompt-lab/blob/main/src/components/layout/layout.tsx): UI shell · Header, sidebar, main workspace, footer, and toast composition. · `src/components/layout/layout.tsx`
- [Sidebar](https://github.com/haideralsh/prompt-lab/blob/main/src/components/sidebar/sidebar.tsx): Explorer UI · Project navigation, search, resize behavior, and settings access. · `src/components/sidebar/sidebar.tsx`
- [Panels](https://github.com/haideralsh/prompt-lab/tree/main/src/components/panels): Workspace UI · Directory, Git, instruction, selected-files, and web panels. · `src/components/panels`
- [State atoms](https://github.com/haideralsh/prompt-lab/blob/main/src/state/atoms.ts): Client state · Global atom-based state for directory, selection, settings, and panel data. · `src/state/atoms.ts`
- [Token UI](https://github.com/haideralsh/prompt-lab/blob/main/src/components/layout/use-token-count-listener.tsx): Metrics · Token counting listeners, charts, and display components used across panels. · `src/components/layout/use-token-count-listener.tsx`
- [IPC API](https://github.com/haideralsh/prompt-lab/tree/main/src/api): Frontend bridge · Typed client calls into the Tauri backend for directory, git, instruction, selection, settings, and web actions. · `src/api`

### Backend

Rust Tauri commands, events, and local persistence

- [Directory API](https://github.com/haideralsh/prompt-lab/tree/main/src-tauri/src/api/directory): Workspace entry · Directory pick, recent directories, and listing from the backend. · `src-tauri/src/api/directory`
- [Tree API](https://github.com/haideralsh/prompt-lab/tree/main/src-tauri/src/api/tree): File tree · Indexing, caching, selection, search, and render pipeline for project files. · `src-tauri/src/api/tree`
- [Git API](https://github.com/haideralsh/prompt-lab/tree/main/src-tauri/src/api/git): Git context · Repository status, watch events, and tokenization for change context. · `src-tauri/src/api/git`
- [Instruction API](https://github.com/haideralsh/prompt-lab/tree/main/src-tauri/src/api/instruction): Prompt presets · Create, edit, validate, and persist reusable instruction content. · `src-tauri/src/api/instruction`
- [Web API](https://github.com/haideralsh/prompt-lab/tree/main/src-tauri/src/api/web): Web capture · Scrapes pages and fetches favicons for web-based prompt context. · `src-tauri/src/api/web`
- [Clipboard](https://github.com/haideralsh/prompt-lab/tree/main/src-tauri/src/api/clipboard): Desktop integration · Copies assembled context out to the system clipboard. · `src-tauri/src/api/clipboard`
- [Editor](https://github.com/haideralsh/prompt-lab/tree/main/src-tauri/src/api/editor): Desktop integration · Opens files in the user’s preferred local editor. · `src-tauri/src/api/editor`
- [Local store](https://github.com/haideralsh/prompt-lab/blob/main/src-tauri/src/store.rs): Persistence · Rust-side local persistence for settings and workspace-related data. · `src-tauri/src/store.rs`

### Shared

Data models and token-aware helpers used across the app

- [Shared types](https://github.com/haideralsh/prompt-lab/tree/main/src/types): Data models · Directory, file-tree, git, and token type definitions shared in the frontend. · `src/types`
- [Helpers](https://github.com/haideralsh/prompt-lab/tree/main/src/helpers): UI logic · Selection preservation, token sorting, and window-title updates used by the shell. · `src/helpers`
- **Context build**: Workflow · Combines selected files, git changes, instructions, and web captures into prompt-ready context.

## Connections

- App shell → Layout: renders · The app entry composes the main desktop shell.
- Layout → Sidebar: contains · The shell includes the project sidebar.
- Layout → Panels: contains · The shell hosts the main workspace panels.
- Layout → Token UI: shows · Token metrics are surfaced in the shell.
- Sidebar → State atoms: reads/writes · Navigation, search, and settings are driven by shared state.
- Panels → State atoms: reads/writes · Panels coordinate selected files, instructions, pages, and project context.
- Panels → Context build: feeds · Panel content contributes to the final prompt payload.
- IPC API → Directory API: calls · Frontend requests workspace selection and directory listing.
- IPC API → Tree API: calls · Frontend requests tree indexing, search, selection, and rendering.
- IPC API → Git API: calls · Frontend requests repository status and receives updates.
- IPC API → Instruction API: calls · Frontend manages saved instructions through backend commands.
- IPC API → Web API: calls · Frontend fetches scraped web content and favicons.
- IPC API → Clipboard: calls · Frontend copies assembled context to the clipboard.
- IPC API → Editor: calls · Frontend opens files in an external editor.
- Directory API → Local store: persists · Recent directories and workspace data are stored locally.
- Tree API → Shared types: uses · Tree data structures are shared across the UI boundary.
- Git API → Token UI: emits counts · Git diff and status token counts drive UI metrics.
- Instruction API → Context build: adds · Saved instructions become part of prompt composition.
- Web API → Context build: adds · Scraped web pages become part of prompt composition.
- Git API → Context build: adds · Git status and diffs are incorporated into context.
- Tree API → Context build: adds · Selected files and tree-derived content feed context composition.
- Helpers → State atoms: normalizes · Selection and display helpers reshape shared UI state.
- Helpers → Token UI: orders · Token-aware sorting and display logic influence UI presentation.
