# gitbutlerapp/gitbutler architecture

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

- Interactive diagram: https://gitdiagram.com/gitbutlerapp/gitbutler
- Repository: https://github.com/gitbutlerapp/gitbutler

## Overview

##### Main Application Components

a. Frontend Layer:
- UI Components (/packages/ui)
- Desktop App Interface (/apps/desktop)
- Web Interface (/apps/web)
- Shared Components (/packages/shared)

b. Backend Layer (Rust):
- Branch Management System (/crates/gitbutler-branch-actions)
- Git Operations (/crates/gitbutler-git)
- Virtual Branch System (/crates/gitbutler-branch)
- Project Management (/crates/gitbutler-project)
- User Management (/crates/gitbutler-user)

c. Integration Layer:
- A section for "External Integrations":
- GitHub Integration
- SSH/GPG Systems
- AI Services (OpenAI)
- Cloud Sync Services

##### Key Architectural Components

- Tauri Bridge (connecting Frontend and Backend)
- Virtual Branch Manager (core feature)
- File System Watcher (/crates/gitbutler-watcher)
- State Management System
- Authentication System

##### Data Flow Patterns

Flow for key operations:
- Virtual Branch Operations
- Git Operations
- User Authentication
- File Change Monitoring
- AI Integration

##### Component Details

For each major component, include:
- Name
- Primary responsibility
- Key dependencies
- Communication protocols

##### External Systems

Connections to:
- Git repositories
- GitHub API
- OpenAI API
- Cloud storage

##### Cross-Cutting Concerns

Sections for:
- Error handling (/crates/gitbutler-error)
- Configuration management (/crates/gitbutler-config)
- Security features (/crates/gitbutler-secret)
- Logging system

##### Development Tools

A section showing:
- Testing infrastructure
- Build system
- Development tools

- The separation between frontend and backend
- The central role of the virtual branch system
- The event-driven nature of the file watching system
- The modularity of the codebase
- The integration points with external services

Key Relationships to Highlight:
##### How external services are integrated

Remember to:
- Use consistent styling
- Related components
- Clear boundaries between systems

This architecture should reflect GitButler's unique approach to Git branch management while maintaining a clear separation of concerns and modularity in the codebase.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Styles
    classDef frontend fill:#3498db,stroke:#2980b9,color:white
    classDef backend fill:#2ecc71,stroke:#27ae60,color:white
    classDef integration fill:#f1c40f,stroke:#f39c12,color:black
    classDef core fill:#9b59b6,stroke:#8e44ad,color:white
    classDef tools fill:#e74c3c,stroke:#c0392b,color:white

    %% Legend
    subgraph Legend
        F[Frontend]:::frontend
        B[Backend]:::backend
        I[Integration]:::integration
        C[Core]:::core
        T[Tools]:::tools
    end

    %% Frontend Layer
    subgraph Frontend
        UI[UI Components]:::frontend
        Desktop[Desktop App]:::frontend
        Web[Web Interface]:::frontend
        Shared[Shared Components]:::frontend
        StateManagement[State Management]:::frontend
    end

    %% Backend Layer
    subgraph Backend
        BranchMgmt[Branch Management]:::backend
        GitOps[Git Operations]:::backend
        VirtualBranch[Virtual Branch System]:::backend
        ProjectMgmt[Project Management]:::backend
        UserMgmt[User Management]:::backend
    end

    %% Integration Layer
    subgraph Integrations
        GitHub[GitHub Integration]:::integration
        SSHGPG[SSH/GPG Systems]:::integration
        AI[AI Services]:::integration
        CloudSync[Cloud Sync]:::integration
    end

    %% Core Architecture
    subgraph Core
        TauriBridge[Tauri Bridge]:::core
        FSWatcher[File System Watcher]:::core
        Auth[Authentication]:::core
        ErrorHandling[Error Handling]:::core
        Config[Configuration]:::core
        Logging[Logging System]:::core
    end

    %% Development Tools
    subgraph DevTools
        Testing[Testing Infrastructure]:::tools
        BuildSystem[Build System]:::tools
    end

    %% Connections
    Frontend --> TauriBridge
    TauriBridge --> Backend
    FSWatcher --> GitOps
    VirtualBranch --> GitOps
    Auth --> UserMgmt
    GitHub --> CloudSync
    AI --> TauriBridge
    ErrorHandling --> TauriBridge
    Config --> TauriBridge
    Logging --> TauriBridge

    %% Click Events
    click UI "https://github.com/gitbutlerapp/gitbutler/tree/master/packages/ui"
    click Desktop "https://github.com/gitbutlerapp/gitbutler/tree/master/apps/desktop"
    click Web "https://github.com/gitbutlerapp/gitbutler/tree/master/apps/web"
    click Shared "https://github.com/gitbutlerapp/gitbutler/tree/master/packages/shared"
    click StateManagement "https://github.com/gitbutlerapp/gitbutler/tree/master/packages/shared/src/lib/redux"
    click BranchMgmt "https://github.com/gitbutlerapp/gitbutler/tree/master/crates/gitbutler-branch-actions"
    click GitOps "https://github.com/gitbutlerapp/gitbutler/tree/master/crates/gitbutler-git"
    click VirtualBranch "https://github.com/gitbutlerapp/gitbutler/tree/master/crates/gitbutler-branch"
    click ProjectMgmt "https://github.com/gitbutlerapp/gitbutler/tree/master/crates/gitbutler-project"
    click UserMgmt "https://github.com/gitbutlerapp/gitbutler/tree/master/crates/gitbutler-user"
    click GitHub "https://github.com/gitbutlerapp/gitbutler/tree/master/crates/gitbutler-forge/src/github"
    click SSHGPG "https://github.com/gitbutlerapp/gitbutler/tree/master/crates/gitbutler-secret"
    click AI "https://github.com/gitbutlerapp/gitbutler/tree/master/apps/desktop/src/lib/ai"
    click CloudSync "https://github.com/gitbutlerapp/gitbutler/tree/master/crates/gitbutler-sync"
    click TauriBridge "https://github.com/gitbutlerapp/gitbutler/tree/master/crates/gitbutler-tauri"
    click FSWatcher "https://github.com/gitbutlerapp/gitbutler/tree/master/crates/gitbutler-watcher"
    click Auth "https://github.com/gitbutlerapp/gitbutler/blob/master/crates/gitbutler-user/src/controller.rs"
    click ErrorHandling "https://github.com/gitbutlerapp/gitbutler/tree/master/crates/gitbutler-error"
    click Config "https://github.com/gitbutlerapp/gitbutler/tree/master/crates/gitbutler-config"
    click Logging "https://github.com/gitbutlerapp/gitbutler/blob/master/crates/gitbutler-tauri/src/logs.rs"
    click Testing "https://github.com/gitbutlerapp/gitbutler/tree/master/crates/gitbutler-testsupport"
    click BuildSystem "https://github.com/gitbutlerapp/gitbutler/blob/master/crates/gitbutler-tauri/build.rs"
```
