# debian/apt architecture

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

- Interactive diagram: https://gitdiagram.com/debian/apt
- Repository: https://github.com/debian/apt

## Overview

##### Project Type and Purpose
- This is a large, modular C++‐based command-line package manager (“apt”) for Debian and derivatives.
- It exposes multiple client binaries (apt-get, apt-cache, apt, etc.) that sit on top of core libraries (libapt-pkg, libapt-inst).
- Responsibilities include: reading config, fetching and parsing package indices, resolving dependencies, downloading packages via pluggable “methods,” and invoking dpkg to install.

##### High-Level Architectural Components
a. CLI Frontends
- Binaries under `cmdline/` and top-level executables (apt-get, apt-cache, apt, apt-ftparchive, etc.).
- Each binary parses arguments, loads configuration, then invokes core library APIs.
b. Core Libraries
- libapt-pkg: configuration, cache management, index parsing, dependency resolution (pkgDepCache, pkgProblemResolver), progress, JSON hooks.
- libapt-inst: interfaces to installation routines and dpkg (“pkgDpkgPm”).
c. Acquisition Subsystem
- AcquireWorker and AcquireMethod abstractions (“methods/”): HTTP, FTP, file, copy, cdrom, etc.
- A simple text-protocol between core and method backends.
- pluggable modules for different transport protocols.
d. Package Index Tools
- apt-ftparchive (ftparchive/): generates Packages, Sources, Release files.
e. Configuration & Localization
- Configuration readers under `apt-pkg/aptconfiguration.*` reading `/etc/apt/apt.conf`, overrides, environment.
- Internationalization pipelines (`po/`, translations in doc/).
f. Integration Points
- External dependency solvers (EDSP) & installation planners (EIPP) via protocol specs in doc/.
- Invocation of dpkg for actual package unpack/install.
- Interaction with underlying filesystem (private-cache, private-utils).
g. Test Harnesses
- Integration tests (`test/integration/`) using shell‐based framework.
- Unit tests (`test/libapt/`) using Google Test.
- Interactive helper tools (`test/interactive-helper/`).

##### Relationships & Data Flows
- User → CLI Frontend: command invocation.
- CLI → Core Library: passes parsed options.
- Core Library → Config Module: loads config files.
- Core Library → Cache & Index Parser: reads local package lists or generates indices via ftparchive.
- Core Library → Dependency Resolver: marks packages, runs pkgProblemResolver.
- Core Library → Acquire Subsystem: requests downloads; AcquireWorker dispatches to a specific method plugin.
- Acquire Method → Remote Service: HTTP/FTP/CDROM → retrieves .deb and index files.
- Core Library → libapt-inst: orchestrates package installation order, calls pkgDpkgPm → dpkg.
- Core Library → External Solvers/Planners (optional) via EDSP/EIPP protocols.
- Core Library → CLI: reports progress, errors, output.

##### Architectural Patterns & Principles
- Layered Architecture:
1. Presentation (CLI)
2. Application (Core Library: config, cache, resolver)
3. Service Layer (Acquisition subsystem)
4. Infrastructure (OS, dpkg, network)
- Plugin/Strategy Pattern for “methods” (download strategies).
- Dependency Inversion: core logic depends on abstract AcquireMethod interface.
- Separation of concerns: index generation (ftparchive), dependency solving, downloading, installation.
- Extensive use of CMake for build modularization, per-component targets.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% CLI Frontends
    subgraph "CLI Frontends" 
        direction TB
        APT["apt"]:::exe
        APT_GET["apt-get"]:::exe
        APT_CACHE["apt-cache"]:::exe
        APT_INTERNAL_PLANNER["apt-internal-planner"]:::exe
        APT_INTERNAL_SOLVER["apt-internal-solver"]:::exe
    end

    %% Core Library
    subgraph "Core Library (libapt-pkg & libapt-inst)" 
        direction TB
        subgraph "Configuration & Logging"
            CFG["aptconfiguration"]:::lib
        end
        subgraph "Cache & Index Parser"
            INDEX_COPY["indexcopy"]:::lib
            INDEX_FILE["indexfile"]:::lib
        end
        subgraph "Dependency Resolver"
            PKG_CACHE["pkgcache"]:::lib
            SOLVER["solver3"]:::lib
        end
        subgraph "JSON Hooks & Progress"
            PROGRESS["install-progress"]:::lib
            PRETTY["prettyprinters"]:::lib
        end
        subgraph "Installer API"
            DPKG_PM["pkgDpkgPm"]:::lib
        end
    end

    %% Acquisition Subsystem
    subgraph "Acquisition Subsystem" 
        direction TB
        ACQ_WORKER["AcquireWorker"]:::lib
        ACQ_METHOD["AcquireMethod"]:::lib
        subgraph "Methods Plugins"
            direction TB
            HTTP["http"]:::plugin
            FTP["ftp"]:::plugin
            FILE["file"]:::plugin
            CDROM["cdrom"]:::plugin
            COPY["copy"]:::plugin
            MIRROR["mirror"]:::plugin
        end
    end

    %% Package Index Tools
    FT["apt-ftparchive"]:::exe

    %% External Services
    subgraph "External Services"
        direction TB
        REPO["Debian Repo (HTTP/FTP)"]:::external
        DPKG["dpkg"]:::external
        EDSP_EXT["External Solver/Planner"]:::external
    end

    %% Test Harnesses
    subgraph "Tests"
        direction TB
        INTEG["Integration Tests"]:::test
        UNIT["Unit Tests"]:::test
        INTERACT["Interactive Helpers"]:::test
    end

    %% Connections
    User([User]):::external -->|invokes| APT
    User -->|invokes| APT_GET
    User -->|invokes| APT_CACHE
    User -->|invokes| APT_INTERNAL_PLANNER
    User -->|invokes| APT_INTERNAL_SOLVER

    APT -->|"parses args & calls API"| CFG
    APT_GET -->|"parses args & calls API"| CFG
    APT_CACHE -->|"parses args & calls API"| CFG
    APT_INTERNAL_PLANNER -->|"invokes EDSP interface"| EDSP["EDSP Handler"]:::lib
    APT_INTERNAL_SOLVER -->|"invokes EIPP interface"| EDSP

    CFG -->|Load Config| INDEX_COPY
    INDEX_COPY -->|Parse Index| INDEX_FILE
    INDEX_FILE -->|Populate Cache| PKG_CACHE
    PKG_CACHE -->|Resolve| SOLVER
    SOLVER -->|JSON Hooks| PROGRESS
    PROGRESS -->|Report| APT
    SOLVER -->|prepare install| DPKG_PM
    DPKG_PM -->|invoke dpkg| DPKG

    SOLVER -->|optional| EDSP_EXT

    CFG -->|source lists| INDEX_COPY

    SOLVER -->|requests download| ACQ_WORKER
    ACQ_WORKER -->|uses| ACQ_METHOD
    ACQ_METHOD -->|dispatch| HTTP
    ACQ_METHOD -->|dispatch| FTP
    ACQ_METHOD -->|dispatch| FILE
    ACQ_METHOD -->|dispatch| CDROM
    ACQ_METHOD -->|dispatch| COPY
    ACQ_METHOD -->|dispatch| MIRROR

    HTTP -->|fetch .deb| REPO
    FTP -->|fetch .deb| REPO
    FILE -->|read .deb| REPO
    CDROM -->|read .deb| REPO
    COPY -->|copy .deb| REPO
    MIRROR -->|mirror .deb| REPO

    FT -->|generate indices| INDEX_FILE

    INTEG -->|test CLI & Core| APT
    INTEG -->|test Core & Acquire| ACQ_WORKER
    UNIT -->|test core lib| CFG
    UNIT -->|test resolver| SOLVER
    INTERACT -->|assist integration| INTEG

    %% Click Events
    click APT "https://github.com/debian/apt/blob/main/cmdline/apt.cc"
    click APT_GET "https://github.com/debian/apt/blob/main/cmdline/apt-get.cc"
    click APT_CACHE "https://github.com/debian/apt/blob/main/cmdline/apt-cache.cc"
    click APT_INTERNAL_PLANNER "https://github.com/debian/apt/blob/main/cmdline/apt-internal-planner.cc"
    click APT_INTERNAL_SOLVER "https://github.com/debian/apt/blob/main/cmdline/apt-internal-solver.cc"
    click CFG "https://github.com/debian/apt/blob/main/apt-pkg/aptconfiguration.cc"
    click INDEX_COPY "https://github.com/debian/apt/blob/main/apt-pkg/indexcopy.cc"
    click INDEX_FILE "https://github.com/debian/apt/blob/main/apt-pkg/indexfile.cc"
    click PKG_CACHE "https://github.com/debian/apt/blob/main/apt-pkg/pkgcache.cc"
    click SOLVER "https://github.com/debian/apt/blob/main/apt-pkg/solver3.cc"
    click PROGRESS "https://github.com/debian/apt/blob/main/apt-pkg/install-progress.cc"
    click PRETTY "https://github.com/debian/apt/blob/main/apt-pkg/prettyprinters.cc"
    click DPKG_PM "https://github.com/debian/apt/blob/main/apt-pkg/deb/dpkgpm.cc"
    click ACQ_WORKER "https://github.com/debian/apt/blob/main/apt-pkg/acquire-worker.cc"
    click ACQ_METHOD "https://github.com/debian/apt/blob/main/apt-pkg/acquire-method.cc"
    click HTTP "https://github.com/debian/apt/blob/main/methods/http.cc"
    click FTP "https://github.com/debian/apt/blob/main/methods/ftp.cc"
    click FILE "https://github.com/debian/apt/blob/main/methods/file.cc"
    click CDROM "https://github.com/debian/apt/blob/main/methods/cdrom.cc"
    click COPY "https://github.com/debian/apt/blob/main/methods/copy.cc"
    click MIRROR "https://github.com/debian/apt/blob/main/methods/mirror.cc"
    click FT "https://github.com/debian/apt/blob/main/ftparchive/apt-ftparchive.cc"
    click EDSP "https://github.com/debian/apt/blob/main/apt-pkg/edsp.cc"
    click INTEG "https://github.com/debian/apt/tree/main/test/integration/"
    click UNIT "https://github.com/debian/apt/tree/main/test/libapt/"
    click INTERACT "https://github.com/debian/apt/tree/main/test/interactive-helper/"

    %% Styles
    classDef exe fill:#f9f,stroke:#333,stroke-width:1px
    classDef lib fill:#bbf,stroke:#333,stroke-width:1px
    classDef plugin fill:#bfb,stroke:#333,stroke-width:1px
    classDef external fill:#ffb,stroke:#333,stroke-width:1px
    classDef test fill:#fbb,stroke:#333,stroke-width:1px
```
