# canonical/apport architecture

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

- Interactive diagram: https://gitdiagram.com/canonical/apport
- Repository: https://github.com/canonical/apport

## Overview

##### Project type and purpose
- This is an open-source system utility for Linux called “Apport.” It hooks into the kernel’s coredump handler and various language runtimes to intercept program crashes, collect diagnostic data, and forward reports to bug trackers (Launchpad, GitHub, etc.). It also offers interactive UIs (CLI, GTK, KDE) for manual bug filing. Its plugin architecture allows distribution-specific packaging hooks and backends.

##### File structure
- Top-level directories:
- apport/              – Core Python library (crash collection, data models, hook registration)
- bin/                  – Front-end executables (apport-bug, apport-cli, apport-retrace, etc.)
- gtk/, kde/, java/     – UI front-ends and language-specific hooks
- debhelper/, setuptools_apport/ – Packaging hooks for Debian (debhelper) and setuptools (Python packages)
- etc/                  – Default configuration files and report-ignore lists
- problem_report.py     – Single-file wrapper for constructing problem reports
- crashdb_impl/         – Modular implementations for storing/querying crash databases (Debian, GitHub, Launchpad, memory)
- packaging_impl/       – Pluggable backends for resolving package metadata (apt/dpkg, rpm)
- pyproject.toml, setup.py – Build and packaging scripts
- tests/                – Unit, integration, and system tests covering all components
- Key patterns:
- Plugin architecture – crashdb_impl and packaging_impl directories implement abstract interfaces defined in crashdb.py and packaging.py.
- Layered CLI/UI separation – core library (apport/*.py) is invoked by multiple front-ends in bin/, gtk/, kde/, java/.
- Service integration – data/systemd and udev define how Apport hooks into the OS at boot or on coredump events.

##### README for additional insights
- Confirms the core feature set (signal crashes, Python exceptions, UI choices, hook extensibility, backend reporting).
- Mentions documentation in doc/ for data formats and hook conventions.
- Describes deployment via systemd, init scripts, and how to enable/disable apport.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% OS Integration Layer
    subgraph "OS Integration Layer"
        direction TB
        KernelCoredump["Kernel Coredump Handler"]:::osIntegration
        SystemdHook["systemd units"]:::osIntegration
        UdevRules["udev rules"]:::osIntegration
    end

    %% Core Library Layer
    subgraph "Core Library"
        direction TB
        CoreEntry["Core Library"]:::coreLib
        CrashdbInterface["crashdb.py (abstract)"]:::coreLib
        PackagingInterface["packaging.py (abstract)"]:::coreLib
        ReportCode["report.py"]:::coreLib
        ProblemReport["problem_report.py"]:::coreLib
        HookUtils["hookutils.py"]:::coreLib
        HookUI["hook_ui.py"]:::coreLib
        PackageInfo["package_info.py"]:::coreLib
        SandboxUtils["sandboxutils.py"]:::coreLib
    end

    %% Plugin Layer
    subgraph "Plugin Layer"
        direction TB
        CrashdbImpl["crashdb_impl/"]:::plugin
        PackagingImpl["packaging_impl/"]:::plugin
        GeneralHooks["data/general-hooks/"]:::plugin
        PackageHooks["data/package-hooks/"]:::plugin
    end

    %% Front-End Layer
    subgraph "Front-End Layer"
        direction TB
        CLI["CLI Executables"]:::frontend
        GTKUI["GTK UI"]:::frontend
        KDEUI["KDE UI"]:::frontend
        JavaHook["Java Exception Hook"]:::frontend
    end

    %% Configuration
    subgraph "Configuration"
        direction TB
        ConfigFiles["Config Files (etc/apport/)"]:::config
        DataConfig["data/apport.conf"]:::config
    end

    %% External Services
    subgraph "External Services"
        direction TB
        BugTrackers["Bug Trackers"]:::external
        PackageManagers["Package Managers"]:::external
        DebugSymbolServer["Debug Symbol Server"]:::external
    end

    %% Data Flow
    KernelCoredump --> SystemdHook
    KernelCoredump --> UdevRules
    SystemdHook --> CoreEntry
    UdevRules --> CoreEntry

    CoreEntry --> PackagingInterface
    CoreEntry --> HookUtils
    CoreEntry --> GeneralHooks
    CoreEntry --> PackageHooks
    CoreEntry --> PackageInfo
    CoreEntry --> SandboxUtils
    CoreEntry --> ReportCode
    CoreEntry --> ProblemReport

    ReportCode --> CLI
    ReportCode --> GTKUI
    ReportCode --> KDEUI
    ReportCode --> JavaHook

    CLI --> CrashdbImpl
    GTKUI --> CrashdbImpl
    KDEUI --> CrashdbImpl
    JavaHook --> CrashdbImpl

    PackagingImpl --> PackageManagers
    CrashdbImpl --> BugTrackers

    CLI --> DebugSymbolServer

    ConfigFiles --- CoreEntry
    DataConfig --- CoreEntry

    %% Plugins integration
    PackagingInterface --> PackagingImpl
    CrashdbInterface --> CrashdbImpl

    %% Click Events
    click SystemdHook "https://github.com/canonical/apport/tree/main/data/systemd/"
    click UdevRules "https://github.com/canonical/apport/blob/main/udev/50-apport.rules"
    click CrashdbInterface "https://github.com/canonical/apport/blob/main/apport/crashdb.py"
    click PackagingInterface "https://github.com/canonical/apport/blob/main/apport/packaging.py"
    click ReportCode "https://github.com/canonical/apport/blob/main/apport/report.py"
    click ProblemReport "https://github.com/canonical/apport/blob/main/problem_report.py"
    click HookUtils "https://github.com/canonical/apport/blob/main/apport/hookutils.py"
    click HookUI "https://github.com/canonical/apport/blob/main/apport/hook_ui.py"
    click PackageInfo "https://github.com/canonical/apport/blob/main/apport/package_info.py"
    click SandboxUtils "https://github.com/canonical/apport/blob/main/apport/sandboxutils.py"
    click CrashdbImpl "https://github.com/canonical/apport/tree/main/apport/crashdb_impl/"
    click PackagingImpl "https://github.com/canonical/apport/tree/main/apport/packaging_impl/"
    click GeneralHooks "https://github.com/canonical/apport/tree/main/data/general-hooks/"
    click PackageHooks "https://github.com/canonical/apport/tree/main/data/package-hooks/"
    click CLI "https://github.com/canonical/apport/tree/main/bin/apport-cli"
    click GTKUI "https://github.com/canonical/apport/tree/main/gtk/apport-gtk"
    click KDEUI "https://github.com/canonical/apport/tree/main/kde/apport-kde"
    click JavaHook "https://github.com/canonical/apport/blob/main/java/com/ubuntu/apport/ApportUncaughtExceptionHandler.java"
    click ConfigFiles "https://github.com/canonical/apport/tree/main/etc/apport/"
    click DataConfig "https://github.com/canonical/apport/blob/main/data/apport.conf"

    %% Styles
    classDef osIntegration fill:#FFD699,stroke:#E69500
    classDef coreLib fill:#DDEEFF,stroke:#3399FF
    classDef plugin fill:#E6FFCC,stroke:#99CC00
    classDef frontend fill:#FFE6E6,stroke:#FF6666
    classDef external fill:#F0E68C,stroke:#B8860B
    classDef config fill:#E8E8E8,stroke:#A9A9A9
```
