# ungoogled-software/ungoogled-chromium-windows architecture

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

- Interactive diagram: https://gitdiagram.com/ungoogled-software/ungoogled-chromium-windows
- Repository: https://github.com/ungoogled-software/ungoogled-chromium-windows

## Overview

##### Project Type and Purpose
- This project is a specialized build and packaging system for ungoogled-chromium on Windows. Its main purpose is to automate source code retrieval, patch application, compilation, and package creation (installer and zip archive) while also integrating with CI tools.
- The README emphasizes detailed build instructions, external environment setup (Visual Studio, Python, MSYS2), patch management, and dependency updates – highlighting that it is as much a build orchestration system as it is a packaging system.

##### Analyzing the File Structure
- Top-Level Directories & Files:
- .github: Contains GitHub Actions for CI/CD, which includes custom actions for staging builds and integration with winget (for installing the packaged app).
- devutils: Scripts for patch checking, tag version printing, and environment variable setup. These support developer workflows and patch consistency.
- patches: Contains a deep hierarchy of patches (organized by series and platform: Windows-specific patches for Chromium) used during the build process.
- build.py and package.py: Core Python scripts used to drive the build and packaging operations.
- downloads.ini and revision.txt: Configuration files for managing external downloads and source revision tracking.
- flags.windows.gn: A configuration file that affects build settings like target architecture.
- ungoogled-chromium: Likely a submodule containing the upstream source, representing the core Chromium codebase.
- The file tree shows a clear separation between CI/CD configuration (.github), build automation (Python scripts, configuration files), patch management, and developer utilities.

##### Architectural Components
A. External Environment & Dependencies
- Visual Studio and Windows SDK: Needed for the compilation process.
- Python (3.8+): The interpreter for running build.py, package.py, and other scripts.
- MSYS2 and associated tools (quilt, dos2unix): Utilized specifically for patch management and developer setup.
- Git: For source retrieval (cloning repositories and updating submodules).
- External packages: 7-Zip, NodeJS, ninja, etc. (as mentioned in the README) are integrated into the process.
B. Source & Download Management
- downloads.ini defines external source URLs and checksums.
- The ungoogled-chromium submodule (and related utilities in ungoogled-chromium/utils) that manage cloning and fetching the Chromium code.
C. Patch Management
- The patches folder, containing both a “series” file and platform-specific patch scripts, outlines the modifications to be applied to Chromium.
- Developer utilities (in devutils) for checking and updating patches.
D. Build and Packaging Pipeline
- build.py: Orchestrates the overall build process from downloading and applying patches to initiating a Windows build.
- package.py: Creates deliverables (zip archive and installer) from the built binaries.
E. CI/CD Integration
- GitHub Actions workflows (.github/workflows/main.yml) and custom actions (.github/actions/stage and winget) used for automating builds and package distribution.

##### Relationships and Data Flow
- A sequential workflow:
1. Developer or CI trigger initiates the Process.
2. Source Code Retrieval: Git fetches the Chromium source (managed via downloads.ini and ungoogled-chromium submodule).
3. Patch Management: The build scripts call patch utilities (via Python scripts and devutils) to apply the patches from the patches directory.
4. Build Process: build.py invokes the compiler using Visual Studio and MSYS2 tools. Configurations like flags.windows.gn affect the build.
5. Packaging: package.py wraps up the build outputs into a zip archive and an installer.
6. CI/CD Actions: GitHub Actions (and specifically the actions defined under .github) monitor the process and, if required, publish the package (including winget integration for easy installation).

##### Architectural Patterns and Design Principles
- Modularity and separation of concerns: The build process is decomposed into distinct modules (source retrieval, patch application, compilation, packaging, deployment).
- Integration with CI/CD pipelines, showing how automated scripts and developer utilities fit into the system.
- Point out any “customized” automation: The project has its own build flow that intentionally avoids using tools like depot_tools, which signifies a custom orchestration layer.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Dependencies
    subgraph "External Dependencies"
        G1("Visual Studio"):::external
        G2("Python 3.8+"):::external
        G3("MSYS2 & Tools"):::external
        G4("Git"):::external
        G5("7-Zip"):::external
        G6("NodeJS"):::external
        G7("ninja"):::external
    end

    %% Build Trigger
    subgraph "Trigger"
        A("Build Trigger (Developer/CI)"):::event
    end

    %% Source Code Management
    subgraph "Source Code Management"
        B1("downloads.ini"):::config
        B2("ungoogled-chromium"):::source
        B3("revision.txt"):::config
    end

    %% Patch Management
    subgraph "Patch Management"
        C1("patches"):::patch
        C2("Developer Utilities"):::script
        C2a("check_patch_files.sh"):::script
        C2b("print_tag_version.sh"):::script
        C2c("set_quilt_vars.sh"):::script
    end

    %% Build Process
    subgraph "Build Process"
        D1("build.py"):::script
        D2("flags.windows.gn"):::config
    end

    %% Packaging
    subgraph "Packaging"
        E1("package.py"):::script
    end

    %% CI/CD Pipeline
    subgraph "CI/CD Pipeline"
        F1(".github"):::ci
        F2(".github/workflows/main.yml"):::ci
        F3(".github/actions/stage"):::ci
        F4(".github/actions/winget"):::ci
    end

    %% Main Flow
    A -->|"initiates"| B1
    B1 -->|"configures"| B2
    B2 -->|"tracks"| B3
    B3 -->|"triggers"| C1
    C1 -->|"utilizes"| C2
    C2 -->|"runs"| D1
    D1 -->|"guided by"| D2
    D2 -->|"feeds into"| E1
    E1 -->|"notified by"| F1
    F1 -->|"defines"| F2
    F1 -->|"includes"| F3
    F1 -->|"includes"| F4

    %% External Dependencies Integration
    G4 ---|"clones source"| B2
    G1 ---|"compiles using"| D1
    G2 ---|"interprets"| D1
    G3 ---|"provides tools for"| D1

    %% Developer Utilities details
    C2 --- C2a
    C2 --- C2b
    C2 --- C2c

    %% Click Events
    click B1 "https://github.com/ungoogled-software/ungoogled-chromium-windows/blob/master/downloads.ini"
    click B2 "https://github.com/ungoogled-software/ungoogled-chromium-windows/tree/master/ungoogled-chromium"
    click B3 "https://github.com/ungoogled-software/ungoogled-chromium-windows/blob/master/revision.txt"
    click C1 "https://github.com/ungoogled-software/ungoogled-chromium-windows/tree/master/patches"
    click C2a "https://github.com/ungoogled-software/ungoogled-chromium-windows/blob/master/devutils/check_patch_files.sh"
    click C2b "https://github.com/ungoogled-software/ungoogled-chromium-windows/blob/master/devutils/print_tag_version.sh"
    click C2c "https://github.com/ungoogled-software/ungoogled-chromium-windows/blob/master/devutils/set_quilt_vars.sh"
    click D1 "https://github.com/ungoogled-software/ungoogled-chromium-windows/blob/master/build.py"
    click D2 "https://github.com/ungoogled-software/ungoogled-chromium-windows/blob/master/flags.windows.gn"
    click E1 "https://github.com/ungoogled-software/ungoogled-chromium-windows/blob/master/package.py"
    click F1 "https://github.com/ungoogled-software/ungoogled-chromium-windows/blob/master/.github"
    click F2 "https://github.com/ungoogled-software/ungoogled-chromium-windows/blob/master/.github/workflows/main.yml"
    click F3 "https://github.com/ungoogled-software/ungoogled-chromium-windows/tree/master/.github/actions/stage"
    click F4 "https://github.com/ungoogled-software/ungoogled-chromium-windows/tree/master/.github/actions/winget"

    %% Styles
    classDef external fill:#AED6F1,stroke:#3A7CA5,stroke-width:2px;
    classDef event fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef config fill:#D5F5E3,stroke:#27AE60,stroke-width:2px;
    classDef source fill:#FAD7A0,stroke:#E67E22,stroke-width:2px;
    classDef patch fill:#F5B7B1,stroke:#C0392B,stroke-width:2px;
    classDef script fill:#D2B4DE,stroke:#8E44AD,stroke-width:2px;
    classDef ci fill:#AED6F1,stroke:#2980B9,stroke-width:2px;
```
