Skip to main content
GitHub Desktop is an open-source Electron-based application written in TypeScript using React for the UI layer.

​
Core Architecture

GitHub Desktop follows a layered architecture pattern that separates concerns across different modules:

Electron Layer

Main and renderer processes handling OS integration and window management

UI Layer

React components and views for user interactions

Business Logic

Stores, state management, and application orchestration

Git Operations

Low-level Git operations using dugite wrapper

​
Project Structure

The application code is organized under app/src/ with the following key directories:

​
Main Directories

app/src/
├── main-process/     # Electron main process code
├── ui/               # React components and views
├── lib/              # Core business logic and utilities
│   ├── git/         # Git operations layer
│   ├── stores/      # State management stores
│   └── api.ts       # GitHub API integration
├── models/           # TypeScript models and types
└── crash/            # Crash reporting UI

​
Key Components

The application uses 57+ Git operation modules in app/src/lib/git/ providing comprehensive Git functionality.

​
Main Process (app/src/main-process/)

  • main.ts: Application entry point, window lifecycle management
  • app-window.ts: Main application window management
  • menu/: Application menu and context menu builders
  • ipc-main.ts: Inter-process communication handlers

​
UI Layer (app/src/ui/)

  • app.tsx: Root React component (~80+ sub-directories)
  • dispatcher/: Central event dispatcher for UI actions
  • lib/: Reusable UI components and utilities
  • Feature-specific components (branches, commits, diff, history, etc.)

​
Business Logic (app/src/lib/)

  • app-state.ts: Central application state interface
  • stores/: State management stores
  • git/: Git operation wrappers
  • api.ts: GitHub REST API client

​
Data Flow

​
Flow Description

  1. User Interaction: User performs an action in the UI
  2. Component Handler: React component captures the event
  3. Dispatcher: Action is dispatched through the central Dispatcher class
  4. Store Processing: AppStore processes the action and coordinates with other stores
  5. Operations: Git operations or API calls are executed
  6. State Update: Application state is updated
  7. Re-render: React components re-render with new state
The Dispatcher pattern provides a clear separation between UI and business logic, making the codebase maintainable and testable.

​
Key Technologies

Electron

Cross-platform desktop framework (macOS, Windows)

React 16.8+

UI library with hooks support

TypeScript

Type-safe JavaScript with strict mode

dugite

Embedded Git distribution wrapper

Dexie.js

IndexedDB wrapper for local data storage

CodeMirror

Text editor for diff viewing

​
State Management

GitHub Desktop uses a custom store-based architecture:
  • AppStore (~8,700 lines): Central store coordinating all application state
  • GitStore: Per-repository Git state (branches, commits, status)
  • RepositoriesStore: Repository list and metadata
  • AccountsStore: User accounts and authentication
  • PullRequestStore: Pull request data and status
  • CommitStatusStore: CI/CD check status
Stores emit events when state changes, allowing React components to subscribe and update automatically.

​
Build System

The application uses webpack for bundling:
  • webpack.common.ts: Shared configuration
  • webpack.development.ts: Development mode with hot reload
  • webpack.production.ts: Production builds with optimization

​
Build Outputs

  • main.js: Electron main process bundle
  • renderer.js: UI renderer process bundle
  • styles/: Compiled SCSS styles

​
Cross-Platform Considerations

The codebase handles platform-specific behavior:
  • macOS: Native menu integration, dock icon updates
  • Windows: Squirrel updater, Windows-specific paths
  • Platform detection via getOS() utility
  • Shell integration (Terminal, Command Prompt, PowerShell)

​
Performance Optimizations

Virtualized Lists

Using react-virtualized for large lists (repos, commits, changes)

Memoization

memoize-one for expensive computations

Lazy Loading

On-demand loading of repository data

Background Tasks

Non-blocking Git operations for large repos

​
Error Handling

Comprehensive error handling throughout:
  • exception-reporting.ts: Crash and error reporting
  • show-uncaught-exception.ts: Unhandled exception UI
  • Error handlers in Dispatcher for graceful degradation
  • Git error parsing and user-friendly messages

​
Next Steps

Electron Structure

Deep dive into main and renderer processes

UI Components

Explore React component architecture

Git Operations

Learn about the Git layer

State Management

Understand stores and data flow

Build docs developers (and LLMs) love

Get started for freeTalk to us