# longbridge/gpui-component architecture

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

- Interactive diagram: https://gitdiagram.com/longbridge/gpui-component
- Repository: https://github.com/longbridge/gpui-component

## Overview

##### Project Type and Purpose
- This is a Cargo workspace containing two primary crates:
- “crates/ui”: the GPUI Component UI library (40+ components, theme support, Markdown/HTML rendering, optional WebView)
- “crates/story”: a Storybook‐style demo application showcasing those components
- Its purpose is to expose a modular, stateless component API on top of the GPUI rendering engine and provide example usages.

##### File Structure
- Top‐level: workspace config (.cargo, Cargo.toml), CI (GitHub Actions), Nix flake, scripts for bootstrapping.
- crates/story/: example code invoking components to render various UI elements.
- BUILD & DEPLOY: Cargo metadata, flake.nix (Nix), GitHub workflows.

##### Sketch the Main System Components
a. Core Rendering Engine (GPUI)
- Provides low‐level windowing, event loop, painting primitives.
- Exposed as the “gpui” crate.
b. GPUI Component Library (crates/ui)
- Stateless UI widgets (Button, Modal, List, Table, etc.)
- Theme & styling engine
- Localization loader
- Highlighter (syntax themes)
- Optional WebView bridge via Wry
c. Storybook Demo App (crates/story)
- Cargo examples that import crates/ui
- Renders component gallery
d. Assets & Configuration
- DEVELOPMENT scripts for bootstrapping and running examples
e. External Services & Tools
- Wry (for WebView)
- GitHub Actions (CI)
- Nix Flake (development environment)

##### Relationships and Data Flows
- The Storybook app invokes the GPUI Component API → which internally calls GPUI’s rendering engine → OS windowing & GPU back-end.
- Component theming reads JSON and locale YAML → feeds into widget style configuration.
- Optional WebView component calls out to Wry → embeds a browser engine → communicates via IPC for events.

##### Architectural Patterns & Principles
- Modular crate separation (ui vs. story).
- Stateless “RenderOnce” pattern: UI components are functions of props → no internal mutable state.
- Feature flags in Cargo.toml for optional WebView support.
- Workspace tooling: unified dependency management and CI pipeline.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% GPUI Component Library
    subgraph "GPUI Component Library (crates/ui)"
        Accordion["Accordion"]:::lib
        Button["Button"]:::lib
        Dock["Dock"]:::lib
        Input["Input"]:::lib
        Text["Text"]:::lib
        Theme["Theme & Styling Engine"]:::lib
        Locale["Localization Loader"]:::lib
        Highlighter["Syntax Highlighter"]:::lib
        WebView["WebView Bridge"]:::lib
        Icon["Icon Integration Module"]:::lib
        Config["default-colors.json"]:::assets
    end

    %% Storybook Demo Application
    subgraph "Storybook Demo Application (crates/story)"
        Entry["Demo App Entry Point (main.rs)"]:::app
        Examples["Story Examples"]:::app
        AssetsLoader["Demo Assets Loader"]:::app
    end

    %% External Components
    GPUICore["GPUI Core"]:::external
    OSGPU["OS GPU & Windowing"]:::external
    Wry["Wry (WebView)"]:::external

    %% Relations: Demo → Library
    Entry -->|"imports API"| Accordion
    Entry --> Button
    Entry --> Dock
    Entry --> Input
    Entry --> Text
    Entry --> Theme

    %% Relations: Library → Core Rendering
    Accordion -->|"renders via"| GPUICore
    Button --> GPUICore
    Dock --> GPUICore
    Input --> GPUICore
    Text --> GPUICore

    %% Assets & Config Usage
    Theme -->|"loads"| Config
    Locale -->|"loads"| Locale
    Icon -->|"loads SVG assets"| Icon
    Highlighter -->|"uses themes"| Config

    %% Optional WebView Feature
    WebView -->|"via feature flag"| Wry

    %% Core → OS GPU
    GPUICore -->|"draws to"| OSGPU

    %% Story Assets
    Entry -->|"loads examples"| Examples
    Entry --> AssetsLoader

    %% Click Events
    click Accordion "https://github.com/longbridge/gpui-component/blob/main/crates/ui/src/accordion.rs"
    click Button "https://github.com/longbridge/gpui-component/blob/main/crates/ui/src/button/mod.rs"
    click Dock "https://github.com/longbridge/gpui-component/blob/main/crates/ui/src/dock/mod.rs"
    click Input "https://github.com/longbridge/gpui-component/blob/main/crates/ui/src/input/mod.rs"
    click Text "https://github.com/longbridge/gpui-component/blob/main/crates/ui/src/text/mod.rs"
    click Theme "https://github.com/longbridge/gpui-component/blob/main/crates/ui/src/theme.rs"
    click Locale "https://github.com/longbridge/gpui-component/blob/main/crates/ui/locales/ui.yml"
    click Highlighter "https://github.com/longbridge/gpui-component/blob/main/crates/ui/src/highlighter/mod.rs"
    click WebView "https://github.com/longbridge/gpui-component/blob/main/crates/ui/src/webview.rs"
    click Icon "https://github.com/longbridge/gpui-component/blob/main/crates/ui/src/icon.rs"
    click Config "https://github.com/longbridge/gpui-component/blob/main/crates/ui/default-colors.json"
    click Entry "https://github.com/longbridge/gpui-component/blob/main/crates/story/src/main.rs"
    click Examples "https://github.com/longbridge/gpui-component/tree/main/crates/story/examples"
    click AssetsLoader "https://github.com/longbridge/gpui-component/blob/main/crates/story/src/assets.rs"

    %% Styles
    classDef lib fill:#cce5ff,stroke:#004085;
    classDef app fill:#d4edda,stroke:#155724;
    classDef external fill:#e2e3e5,stroke:#6c757d;
    classDef assets fill:#fff3cd,stroke:#856404;
```
