# blackboardsh/electrobun architecture

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

- Interactive diagram: https://gitdiagram.com/blackboardsh/electrobun
- Repository: https://github.com/blackboardsh/electrobun

## Overview

##### Main Components

a) Core Runtime Components:
- Bun Runtime (Main Process)
- Native Bindings (Zig)
- System WebView
- RPC Communication Layer

b) Build & Distribution System:
- CLI Tools
- Bundler
- Updater System
- Package Manager Integration

##### Architecture Layers

**┌─────────────────────────────────────────┐**
- Application Layer            │
- (User's TypeScript Code - Main/Views)  │
- ┤
- Electrobun Framework Layer      │
- Browser APIs                         │
- Bun APIs                            │
- RPC System                          │
- ┤
- Native Bridge Layer          │
- Zig Bindings                        │
- ObjectiveC Integration              │
- ┤
- Platform Layer               │
- System WebView                      │
- OS Integration                      │
- ┘

##### Key Relationships to Highlight

a) Process Communication:
- RPC system (src/bun/core/Socket.ts)
- Isolation boundaries between processes

b) Native Integration:
- How Zig bindings connect to platform APIs
- Bridge between TypeScript and native code

##### Specific Components to Detail

a) Core Services (from src/bun/core):
- ApplicationMenu
- BrowserWindow
- BrowserView
- Tray
- Updater

b) Event System (from src/bun/events):
- ApplicationEvents
- TrayEvents
- WebviewEvents
- WindowEvents

##### Build & Distribution Flow

- Build Process
- Packaging
- Update Distribution (bsdiff system)
- Self-extracting bundles

## Diagram (Mermaid)

```mermaid
graph TB
    %% Styles and classes
    classDef application fill:#3498db,stroke:#2980b9,color:white
    classDef framework fill:#2ecc71,stroke:#27ae60,color:white
    classDef native fill:#e67e22,stroke:#d35400,color:white
    classDef platform fill:#95a5a6,stroke:#7f8c8d,color:white
    classDef build fill:#9b59b6,stroke:#8e44ad,color:white

    %% Application Layer
    subgraph AppLayer["Application Layer"]
        UserCode["User TypeScript Code"]:::application
    end

    %% Framework Layer
    subgraph FrameworkLayer["Electrobun Framework Layer"]
        BunRuntime["Bun Runtime"]:::framework
        CoreServices["Core Services"]:::framework
        EventSystem["Event System"]:::framework
        BrowserIntegration["Browser Integration"]:::framework
        
        subgraph CoreServicesDetail["Core Services Detail"]
            AppMenu["Application Menu"]:::framework
            BrowserWin["Browser Window"]:::framework
            BrowserV["Browser View"]:::framework
            TrayService["Tray"]:::framework
            UpdaterService["Updater"]:::framework
        end

        subgraph EventSystemDetail["Event System Detail"]
            AppEvents["Application Events"]:::framework
            TrayEvents["Tray Events"]:::framework
            WebEvents["Webview Events"]:::framework
            WinEvents["Window Events"]:::framework
        end
    end

    %% Native Bridge Layer
    subgraph NativeBridge["Native Bridge Layer"]
        ZigBindings["Zig Bindings"]:::native
        ObjCIntegration["ObjectiveC Integration"]:::native
        RPCSystem["RPC System"]:::native
    end

    %% Platform Layer
    subgraph PlatformLayer["Platform Layer"]
        SystemWebView["System WebView"]:::platform
        OSIntegration["OS Integration"]:::platform
    end

    %% Build System
    subgraph BuildSystem["Build & Distribution"]
        CLITools["CLI Tools"]:::build
        UpdateSystem["Update System"]:::build
        SelfExtract["Self-extracting Bundles"]:::build
        Launcher["Launcher"]:::build
    end

    %% Relationships
    UserCode --> BunRuntime
    BunRuntime --> CoreServices
    BunRuntime --> EventSystem
    CoreServices --> ZigBindings
    EventSystem --> RPCSystem
    ZigBindings --> ObjCIntegration
    ObjCIntegration --> SystemWebView
    RPCSystem --> SystemWebView
    BrowserIntegration --> SystemWebView

    %% Click events for component mapping
    click BunRuntime "https://github.com/blackboardsh/electrobun/blob/main/src/bun/index.ts"
    click ZigBindings "https://github.com/blackboardsh/electrobun/blob/main/src/zig/main.zig"
    click SystemWebView "https://github.com/blackboardsh/electrobun/blob/main/src/zig/macos/webview.zig"
    click RPCSystem "https://github.com/blackboardsh/electrobun/blob/main/src/bun/core/Socket.ts"
    click AppMenu "https://github.com/blackboardsh/electrobun/blob/main/src/bun/core/ApplicationMenu.ts"
    click BrowserWin "https://github.com/blackboardsh/electrobun/blob/main/src/bun/core/BrowserWindow.ts"
    click BrowserV "https://github.com/blackboardsh/electrobun/blob/main/src/bun/core/BrowserView.ts"
    click TrayService "https://github.com/blackboardsh/electrobun/blob/main/src/bun/core/Tray.ts"
    click UpdaterService "https://github.com/blackboardsh/electrobun/blob/main/src/bun/core/Updater.ts"
    click AppEvents "https://github.com/blackboardsh/electrobun/blob/main/src/bun/events/ApplicationEvents.ts"
    click TrayEvents "https://github.com/blackboardsh/electrobun/blob/main/src/bun/events/trayEvents.ts"
    click WebEvents "https://github.com/blackboardsh/electrobun/blob/main/src/bun/events/webviewEvents.ts"
    click WinEvents "https://github.com/blackboardsh/electrobun/blob/main/src/bun/events/windowEvents.ts"
    click ObjCIntegration "https://github.com/blackboardsh/electrobun/blob/main/src/objc/objcWrapper.m"
    click CLITools "https://github.com/blackboardsh/electrobun/blob/main/src/cli/index.ts"
    click UpdateSystem "https://github.com/blackboardsh/electrobun/blob/main/src/bsdiff/bsdiff.zig"
    click SelfExtract "https://github.com/blackboardsh/electrobun/blob/main/src/extractor/main.zig"
    click Launcher "https://github.com/blackboardsh/electrobun/blob/main/src/launcher/main.zig"
    click BrowserIntegration "https://github.com/blackboardsh/electrobun/blob/main/src/browser/index.ts"
```
