# google/breakpad architecture

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

- Interactive diagram: https://gitdiagram.com/google/breakpad
- Repository: https://github.com/google/breakpad

## Overview

##### Project Type and Purpose
- Breakpad is an open-source, cross-platform crash-reporting system.
- It consists of:
– Client libraries that embed in applications (on Linux, macOS, Windows, Android, iOS, Solaris) to catch crashes, generate “minidump” files, and upload them.
– A set of standalone tools (dump_syms, symupload, md2core, etc.) for symbol extraction, conversion, and upload.
– A processor pipeline (minidump_stackwalk, minidump_dump, etc.) that parses minidumps, resolves symbols, and produces human-readable crash reports or machine-readable outputs.
– Third-party dependencies (libcurl, musl, gflags, etc.) and build scripts for autotools, Xcode, Visual Studio, and CI.

##### File‐Structure and Architectural Patterns
- Top-level modules:
– src/client: OS‐specific crash handlers and uploaders.
– src/common: cross-platform utility libraries for parsing, memory I/O, threading, platform abstractions.
– src/google_breakpad: core format definitions and shared data structures.
– src/processor: the crash-report processing engine (stack walking, symbol resolution).
– src/tools: command‐line utilities for symbol dumping, minidump conversion, symbol upload, etc., organized by OS.
– src/third_party: bundled external libraries (curl, libdisasm, musl, headers).
- Architectural style: layered, modular, plugin-like per OS. The client layer depends on common & google_breakpad, the processor layer depends on common & google_breakpad, and tools orchestrate those layers.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Application and Client Libraries
    App["Application"]:::app
    subgraph "Client Libraries (per-platform)" 
        direction TB
        CL_Linux["Linux Client"]:::client
        OtherClients["Other Platforms"]:::client
        subgraph "Linux Client" 
            direction TB
            EH["Exception Handler"]:::client
            MW["Minidump Writer"]:::client
            CRS["Crash-Report Sender"]:::client
        end
    end

    %% Core Libraries
    subgraph "Core Libraries" 
        direction TB
        Common["Common Utility Libraries"]:::core
        GB["Google Breakpad Core"]:::core
        subgraph "Third-Party Dependencies" 
            direction TB
            Libcurl["libcurl"]:::thirdparty
            Libdisasm["libdisasm"]:::thirdparty
            Musl["musl"]:::thirdparty
        end
    end

    %% Tools Layer
    subgraph "Tools" 
        direction TB
        DumpSyms["dump_syms"]:::tools
        SymUploadTool["symupload"]:::tools
    end

    %% Processor Engine
    subgraph "Processor Engine" 
        direction TB
        Stackwalk["minidump_stackwalk"]:::processor
        Dump["minidump_dump"]:::processor
        Resolver["Symbol Resolver"]:::processor
    end

    %% External Services
    SymbolStore["Symbol Store"]:::external
    Report["Crash Report Output"]:::external

    %% Data Flows
    App -->|crash occurs| EH
    EH --> MW
    MW --> CRS
    CRS -->|HTTP POST| SymbolStore
    CRS -->|HTTP POST| DumpSyms
    DumpSyms --> SymUploadTool
    SymUploadTool -->|uploads .sym| SymbolStore
    SymbolStore --> Stackwalk
    SymbolStore --> Dump
    Stackwalk --> Resolver
    Resolver --> Report
    Dump --> Report

    %% Dependencies
    CL_Linux --> Common
    CL_Linux --> GB
    OtherClients --> Common
    OtherClients --> GB
    DumpSyms --> Common
    SymUploadTool --> Common
    Stackwalk --> Common
    Dump --> Common
    Resolver --> Common
    Common --> Libcurl
    Common --> Libdisasm
    Common --> Musl

    %% Click Events
    click CL_Linux "https://github.com/google/breakpad/tree/main/src/client"
    click EH "https://github.com/google/breakpad/blob/main/src/client/linux/handler/exception_handler.cc"
    click MW "https://github.com/google/breakpad/blob/main/src/client/linux/minidump_writer/minidump_writer.cc"
    click CRS "https://github.com/google/breakpad/blob/main/src/client/linux/sender/google_crash_report_sender.cc"
    click Common "https://github.com/google/breakpad/tree/main/src/common"
    click GB "https://github.com/google/breakpad/tree/main/src/google_breakpad/common"
    click Stackwalk "https://github.com/google/breakpad/blob/main/src/processor/minidump_stackwalk.cc"
    click Dump "https://github.com/google/breakpad/blob/main/src/processor/minidump_dump.cc"
    click Resolver "https://github.com/google/breakpad/blob/main/src/processor/basic_source_line_resolver.cc"
    click DumpSyms "https://github.com/google/breakpad/blob/main/src/tools/linux/dump_syms/dump_syms.cc"
    click SymUploadTool "https://github.com/google/breakpad/blob/main/src/tools/linux/symupload/minidump_upload.cc"
    click Libcurl "https://github.com/google/breakpad/tree/main/src/third_party/curl"
    click Libdisasm "https://github.com/google/breakpad/tree/main/src/third_party/libdisasm"
    click Musl "https://github.com/google/breakpad/tree/main/src/third_party/musl"
    click HTTPUpload "https://github.com/google/breakpad/blob/main/src/common/linux/http_upload.cc"
    click SymUploadWin "https://github.com/google/breakpad/blob/main/src/common/windows/sym_upload_v2_protocol.cc"

    %% Styles
    classDef app fill:#D0E6A5,stroke:#333,stroke-width:1px
    classDef client fill:#AEDFF7,stroke:#333,stroke-width:1px
    classDef core fill:#B2F7EF,stroke:#333,stroke-width:1px
    classDef tools fill:#FFD6A5,stroke:#333,stroke-width:1px
    classDef processor fill:#E2B1F3,stroke:#333,stroke-width:1px
    classDef external fill:#F3F1A4,stroke:#333,stroke-width:1px
    classDef thirdparty fill:#CCCCCC,stroke:#333,stroke-width:1px
```
