# alex313031/thoriumos architecture

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

- Interactive diagram: https://gitdiagram.com/alex313031/thoriumos
- Repository: https://github.com/alex313031/thoriumos

## Overview

##### Main Components
- Build Environment & External Dependencies:
– Depot_tools, Chromium source, ChromiumOS source, and the CrOS SDK.
– The host environment where “setup.sh” copies configuration files and creates the new overlay.
- Overlays & Package Layers:
– The overlay directory (e.g., overlay-amd64-frick) that is created and referenced by files in chromeos-base, app-* directories, dev-python, etc.
– Various ebuild directories (app-admin, app-arch, app-misc, app-text, etc.) representing collections of custom package builds.
- Configuration & Integration:
– Configuration files (.googleapikeys, chrome_dev.conf, make.conf, profiles, metadata, kconfigs) that determine build options, compiler optimizations, and API key injection.
– Scripts (setup.sh, build_kernel_image.sh, create-ova, reset_depot_tools.sh, etc.) that drive the build flow.
- Build Output:
– Artifacts like chromiumos_image.bin which are produced after the integration of overlays, custom packages, and source syncing.
- External Services:
– External repositories and resources, such as the upstream chromiumos source (and instructions to sync with gclient), Travis-type build infrastructure, and the API key/signing services for ChromiumOS.

##### Relationships & Data Flows
- The Host Environment contains the source directories (Chromium, ChromiumOS, this overlay repo) that interact via setup scripts.
- The Setup Script (./setup.sh) acts as a gateway, copying configuration data into the ChromiumOS build tree and registering the overlay.
- Within the Build Environment, the build process (using cros_sdk and exports commands) pulls in packages from the overlay directories.
- The overlays (composed of multiple app-*, chromeos-base, dev-python, media-libs, etc.) define the different packages and customized functionalities.
- Configuration files (API keys, chrome_dev.conf) feed into the build process, resulting in a signed, customized OS image.
- The final build output (the chromiumos_image.bin) is then flashed to hardware using tools like BalenaEtcher, dd, or cros_flash.

##### Architectural Patterns and Design Principles
- Modularity: The project is composed of numerous independent overlay directories (separated by type — apps, system utilities, media libraries, etc.) that allow selective customization.
- Layered Architecture: There’s a clear separation between the underlying ChromiumOS/Chromium codebase, the overlay modifications (package recipes and custom configurations), and the build scripts.
- Configuration-as-Code: Much of the build behavior is controlled via configuration files (e.g., make.defaults, profiles, metadata/layout.conf), making the build process reproducible and customizable.
- Integration with Existing Systems: The overlay approach respects the upstream ChromiumOS build methodology, showing adherence to the established practices (e.g., by modifying cros-board overlays).

##### Relevant Technologies and Frameworks
- Build Tools: depot_tools, gclient, cros_sdk, and various shell scripts.
- Package Management: The Gentoo-style ebuild system that organizes custom packages.
- Programming Languages: Shell scripting, Python (present in the dev-python section), and configured build systems.
- Version Control & CI/CD: Git repository configuration (.gclient, .gitignore, .github folder) for versioning and possibly automated builds or contribution guidelines.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Build Environment & External Dependencies
    subgraph "Build Environment & External Dependencies"
        DE1["Depot Tools"]:::external
        DE2["Chromium Source"]:::external
        DE3["ChromiumOS Source"]:::external
        DE4["CrOS SDK"]:::external
        GCLIENT[".gclient"]:::repo
        RESET_DEPOT["reset_depot_tools.sh"]:::repo
        SETUP["setup.sh"]:::repo
    end

    %% Overlays & Package Layers
    subgraph "Overlays & Package Layers"
        APP_ADMIN["app-admin"]:::overlay
        APP_ARCH["app-arch"]:::overlay
        APP_MISC["app-misc"]:::overlay
        APP_TEXT["app-text"]:::overlay
        CHROMEOS_BASE["chromeos-base"]:::overlay
        DEV_PYTHON["dev-python"]:::overlay
        MEDIA_LIBS["media-libs"]:::overlay
    end

    %% Configuration & Integration
    subgraph "Configuration & Integration"
        GOOGLE_API[".googleapikeys"]:::config
        CHROME_DEV["chrome_dev.conf"]:::config
        MAKE_CONF["make.conf"]:::config
        PROFILES["profiles"]:::config
        METADATA["metadata"]:::config
        KCONFIGS["kconfigs"]:::config
    end

    %% Build Scripts
    subgraph "Build Scripts"
        BUILD_KERNEL["build_kernel_image.sh"]:::scripts
        BOARD_SETUP["board_specific_setup.sh"]:::scripts
        CREATE_OVA["create-ova"]:::scripts
        CHECK_SIMD["check_simd.sh"]:::scripts
    end

    %% Build Output
    subgraph "Build Output"
        IMAGES100["images_100_percent"]:::output
        IMAGES200["images_200_percent"]:::output
    end

    %% Deployment Tools (External)
    DT["Deployment Tools (BalenaEtcher,dd,cros_flash)"]:::deployment

    %% Connections from Build Environment to Setup Script
    DE1 -->|"prepare"| SETUP
    DE2 -->|"prepare"| SETUP
    DE3 -->|"prepare"| SETUP
    DE4 -->|"prepare"| SETUP

    %% Setup injects Overlays & Configuration
    SETUP -->|"overlay_register"| CHROMEOS_BASE
    SETUP -->|"config_injection"| GOOGLE_API

    %% Overlays feed into Build Scripts
    APP_ADMIN -->|"packages"| BUILD_KERNEL
    APP_ARCH -->|"packages"| BUILD_KERNEL
    APP_MISC -->|"packages"| BUILD_KERNEL
    APP_TEXT -->|"packages"| BUILD_KERNEL
    DEV_PYTHON -->|"packages"| BUILD_KERNEL
    MEDIA_LIBS -->|"packages"| BUILD_KERNEL
    CHROMEOS_BASE -->|"packages"| BUILD_KERNEL

    %% Configuration files feed into Build Scripts
    PROFILES -->|"settings"| BUILD_KERNEL
    CHROME_DEV -->|"settings"| BUILD_KERNEL
    MAKE_CONF -->|"settings"| BUILD_KERNEL
    METADATA -->|"metadata"| BUILD_KERNEL
    KCONFIGS -->|"configs"| BUILD_KERNEL

    %% Build Scripts produce Build Output
    BUILD_KERNEL -->|"generate"| IMAGES100
    BUILD_KERNEL -->|"generate"| IMAGES200

    %% Build Output flows to Deployment Tools
    IMAGES100 -->|"deploy"| DT
    IMAGES200 -->|"deploy"| DT

    %% Styles
    classDef external fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef overlay fill:#F9E79F,stroke:#B9770E,stroke-width:2px;
    classDef config fill:#ABEBC6,stroke:#1E8449,stroke-width:2px;
    classDef scripts fill:#D2B4DE,stroke:#6C3483,stroke-width:2px;
    classDef output fill:#F5B7B1,stroke:#922B21,stroke-width:2px;
    classDef deployment fill:#FAD7A0,stroke:#B9770E,stroke-width:2px;
    classDef repo fill:#FCF3CF,stroke:#B7950B,stroke-width:2px;

    %% Click Events for Build Environment & External Dependencies
    click GCLIENT "https://github.com/alex313031/thoriumos/blob/main/.gclient"
    click RESET_DEPOT "https://github.com/alex313031/thoriumos/blob/main/reset_depot_tools.sh"
    click SETUP "https://github.com/alex313031/thoriumos/blob/main/setup.sh"

    %% Click Events for Overlays & Package Layers
    click APP_ADMIN "https://github.com/alex313031/thoriumos/tree/main/app-admin"
    click APP_ARCH "https://github.com/alex313031/thoriumos/tree/main/app-arch"
    click APP_MISC "https://github.com/alex313031/thoriumos/tree/main/app-misc"
    click APP_TEXT "https://github.com/alex313031/thoriumos/tree/main/app-text"
    click CHROMEOS_BASE "https://github.com/alex313031/thoriumos/tree/main/chromeos-base"
    click DEV_PYTHON "https://github.com/alex313031/thoriumos/tree/main/dev-python"
    click MEDIA_LIBS "https://github.com/alex313031/thoriumos/tree/main/media-libs"

    %% Click Events for Configuration & Integration
    click GOOGLE_API "https://github.com/alex313031/thoriumos/blob/main/.googleapikeys"
    click CHROME_DEV "https://github.com/alex313031/thoriumos/blob/main/chrome_dev.conf"
    click MAKE_CONF "https://github.com/alex313031/thoriumos/blob/main/make.conf"
    click PROFILES "https://github.com/alex313031/thoriumos/tree/main/profiles"
    click METADATA "https://github.com/alex313031/thoriumos/tree/main/metadata"
    click KCONFIGS "https://github.com/alex313031/thoriumos/tree/main/kconfigs"

    %% Click Events for Build Scripts
    click BUILD_KERNEL "https://github.com/alex313031/thoriumos/blob/main/scripts/build_kernel_image.sh"
    click BOARD_SETUP "https://github.com/alex313031/thoriumos/blob/main/scripts/board_specific_setup.sh"
    click CREATE_OVA "https://github.com/alex313031/thoriumos/tree/main/create-ova"
    click CHECK_SIMD "https://github.com/alex313031/thoriumos/blob/main/check_simd.sh"

    %% Click Events for Build Output
    click IMAGES100 "https://github.com/alex313031/thoriumos/tree/main/images/images_100_percent"
    click IMAGES200 "https://github.com/alex313031/thoriumos/tree/main/images/images_200_percent"
```
