# lineageos/android architecture

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

- Interactive diagram: https://gitdiagram.com/lineageos/android
- Repository: https://github.com/lineageos/android

## Overview

##### Project type and purpose
- This repository is not an application per se but the “manifest” repository for LineageOS.
- It defines which Git repositories (AOSP, device trees, vendor blobs, community projects) are pulled by the Android “repo” tool to assemble a full LineageOS build.
- Snippet XML files (e.g. snippets/lineage.xml, snippets/pixel.xml) provide device- or feature-specific overlays that can be merged into the main manifest.

##### File structure
- Top-level files:
- README.mkdn – high-level instructions on initializing and syncing the repo
- default.xml – the primary manifest listing all upstream Git projects
- snippets/ – supplemental manifest fragments:
- lineage.xml – common customizations for all LineageOS builds
- pixel.xml – device-specific manifest entries for Google Pixel phones
- No src/ or code directories here: this is purely a configuration and orchestration repo.

##### Insights from the README
- Shows that developers use the Android “repo” tool to:
repo init -u https://github.com/LineageOS/android.git -b lineage-22.2 --git-lfs
repo sync
- Mentions Gerrit for patch management and Buildkite/Buildbot for automated builds.

##### Main components
a. Manifest Repository
- default.xml and snippet files define what code is pulled, and how it is organized.
b. Repo Tool
- Client-side orchestration that reads the manifest and clones/syncs all referenced Git repos.
c. Git Servers / Upstream Repos
- AOSP core, LineageOS platform forks, device trees, vendor blobs, community contributions.
d. Local Workspace
- A directory structure populated by `repo sync`, containing dozens of project submodules.
e. Build System
- Buildbot/Buildkite pipelines that monitor the manifest branch, trigger builds on commit.
f. Artifact Storage / Download Server
- Where finished LineageOS builds (OTA zips, recovery images) are uploaded.
g. Gerrit Code Review
- External service for patch submission and review before merging into the manifest or individual sub-repos.

##### Relationships and interactions
- Developer runs `repo init` & `repo sync` → Repo Tool pulls from Git Servers based on Manifest
- Developer submits patches → patches go to Gerrit → after approval they land in individual repos or the manifest
- Buildbot watches manifest branch → on change it triggers a full sync + build pipeline
- Build pipeline produces artifacts → uploads to download server
- Users download artifacts from the server

##### Architectural patterns and principles
- “Single source of truth”: the manifest defines all components and their exact revisions.
- Separation of concerns: manifests for common vs. device-specific configurations (snippets).
- Extensibility: new devices or features can be added by dropping new XML snippet files and including them via the default.xml or by conditional includes.
- Decoupling of code hosting and build orchestration: the repo tool is a thin client, the build servers operate independently.

##### Detail level
- Every manifest-related step: default.xml includes snippet files, conditional includes if any.
- That snippets folder is referenced by the primary manifest.
- That `repo sync` may involve Git LFS if enabled.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Manifest Repository
    subgraph "Manifest Repository"
        MR_DOCS["README.mkdn"]:::config
        defaultXML["default.xml"]:::config
        lineageXML["snippets/lineage.xml"]:::config
        pixelXML["snippets/pixel.xml"]:::config
    end

    %% Developer and Gerrit
    Developer["Developer"]:::external
    Gerrit["Gerrit Code Review"]:::external

    %% Repo Tool
    RepoCLI["Repo CLI (repo init & sync)"]:::orchestration

    %% Git Servers and Local Workspace
    GitServers["Git Servers\n(AOSP, forks, device trees)"]:::external
    LocalWorkspace["Local Workspace"]:::workspace

    %% Build Pipeline and Artifact Storage
    BuildPipeline["Build Pipeline\n(Buildbot/Buildkite)"]:::orchestration
    ArtifactStorage["Artifact Storage\n(Download Server)"]:::artifact
    Users["End Users"]:::external

    %% Relationships
    Developer -->|submits patches| Gerrit
    Gerrit -->|approves & merges| MR_DOCS
    MR_DOCS -->|defines repos| defaultXML
    defaultXML -->|includes| lineageXML
    defaultXML -->|includes| pixelXML

    defaultXML -->|"init reads manifest"| RepoCLI
    RepoCLI -->|"clones/pulls"| GitServers
    GitServers -->|"populates"| LocalWorkspace

    MR_DOCS -->|on change triggers| BuildPipeline
    BuildPipeline -->|"uploads artifacts"| ArtifactStorage
    ArtifactStorage -->|"downloads"| Users

    %% Click Events
    click MR_DOCS "https://github.com/lineageos/android/blob/lineage-22.2//README.mkdn"
    click defaultXML "https://github.com/lineageos/android/blob/lineage-22.2//default.xml"
    click lineageXML "https://github.com/lineageos/android/blob/lineage-22.2//snippets/lineage.xml"
    click pixelXML "https://github.com/lineageos/android/blob/lineage-22.2//snippets/pixel.xml"

    %% Styles
    classDef config fill:#D6EAF8,stroke:#3498DB,color:#1B4F72;
    classDef orchestration fill:#D5F5E3,stroke:#27AE60,color:#145A32;
    classDef external fill:#FADBD8,stroke:#E74C3C,color:#641E16;
    classDef workspace fill:#FCF3CF,stroke:#F1C40F,color:#7D6608;
    classDef artifact fill:#F5EEF8,stroke:#8E44AD,color:#4A235A;
```
