# taasezer/taaos architecture

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

- Interactive diagram: https://gitdiagram.com/taasezer/taaos
- Repository: https://github.com/taasezer/taaos

## Overview

1. **What this repo builds**
   - TaaOS is a Debian 12–based live Linux distribution, not an application. The repository assembles a bootable ISO, installable desktop system, and optional persistent USB image from a Dockerized build pipeline.

2. **Top-level build flow**
   - `build.sh` is the main orchestration entrypoint. It likely cleans prior outputs, builds a dedicated `taaos-builder` container from `docker/Dockerfile`, injects repo content into that container, and runs Debian `live-build` to produce the final ISO.
   - Supporting scripts like `build_taaos.sh`, `clean.sh`, `compile_kernel.sh`, and `init_config.sh` split the build into cleanup, kernel, and configuration phases.

3. **Build-time boundary: containerized build environment**
   - The build happens inside Docker to isolate host dependencies from the ISO toolchain.
   - The repository also carries a large `cache/packages.bootstrap` set of `.deb` files, which acts as an offline/bootstrap package cache for reproducible builds or air-gapped preparation.

4. **Live system composition**
   - The `config/` tree is the core image definition. It maps directly into the final root filesystem and installer media.
   - `config/package-lists/*.list.chroot` defines package groups for different editions or roles: desktop, AI, engineering, firmware, installer, live system, performance, professional, recovery, themes, and Wine.
   - `config/packages.chroot` includes pinned local kernel `.deb` artifacts, while `config/packages.binary` and `config/includes.binary` define files that land on the bootable media side rather than inside the root filesystem.

5. **Runtime filesystem overlays**
   - `config/includes.chroot/` is the main runtime filesystem overlay. It places configuration under `/etc`, user defaults under `/etc/skel`, utilities under `/usr/bin`, `/usr/local/bin`, service units under `/etc/systemd/system`, and documentation/media under `/usr/share`.
   - This is where the distro’s identity is encoded: XFCE settings, terminal styling, wallpaper behavior, boot defaults, security sysctls, SSH hardening, and TaaOS-specific versioning files.

6. **Installer and first-boot path**
   - Calamares is the installation boundary. Its branding and module configs are under `/etc/calamares` and `/usr/lib/calamares/modules`.
   - The live image includes installer-facing hooks and desktop shortcuts, then removes or disables live-only artifacts post-install.
   - First-boot behavior is handled by systemd units such as `taaos-first-boot.service`, `taaos-drivers.service`, and `taaos-update.service`, which coordinate initial setup, driver actions, and maintenance.

7. **System customization and UX layer**
   - The repo heavily customizes XFCE4 through skeleton configs, panel XML, terminal settings, LightDM config, Fastfetch, wallpaper autostart, and a welcome experience.
   - User-facing scripts in `/usr/local/bin` and `/usr/bin` provide distro-branded tools like `taaos-help`, `taaos-doctor`, `taaos-clean`, `taaos-update`, `taaos-wallpaper-fix.sh`, and package helpers.
   - This layer is about presenting a polished desktop and terminal experience after the base OS boots.

8. **Security and hardening subsystem**
   - Security is implemented through layered configuration and scripts rather than one monolithic service.
   - Hardening is applied via `scripts/security/harden-system.sh`, `scripts/system/taaos-harden.sh`, SSH and sysctl snippets, and systemd boot tuning.
   - There is also a “natural engine” safety model in the README, but the concrete repo artifacts point mainly to shell-level, system-level, and service-level hardening in the image.

9. **Automation, diagnostics, and maintenance**
   - `scripts/system/taaos-update.sh`, `taaos-health-check.sh`, `taaos-rescue.sh`, `taaos-boot-analyze.sh`, and related utilities form the distro’s maintenance and recovery toolkit.
   - `scripts/devops/` adds environment bootstrap for developers, while `scripts/performance/optimize-system.sh` handles tuning.
   - These scripts are part of the installed OS image, so they are runtime capabilities rather than build-only helpers.

10. **Specialized capabilities and integrations**
   - The distro is designed around engineering/DevOps workloads, so package groups and scripts support containers, virtualization, AI tooling, Git workflows, and recovery workflows.
   - `config/includes.chroot/var/lib/taaos/packages/*.list` suggests curated package sets for browser/editor tooling or optional app bundles.
   - The README’s mention of n8n, Portainer, and Cockpit indicates service-oriented management tools, even if their actual setup is driven by package selection and included configs rather than explicit app source in this repo.

11. **Kernel and boot path**
   - The presence of `config/kernel/`, `compile_kernel.sh`, and kernel `.deb` artifacts under `config/packages.chroot/` shows the project can ship a custom or pinned kernel.
   - Bootloader configurations for both GRUB EFI and GRUB PC are under `config/bootloaders/`, which means the final image supports both UEFI and legacy BIOS boot paths.

12. **Testing and validation boundary**
   - `tests/launch_qemu_vm.ps1` and `tests/launch_vbox_vm.ps1` indicate post-build validation is done by booting the image in virtual machines.
   - This makes the architecture a full image pipeline: source config → Dockerized build → ISO output → VM smoke test → release artifacts in `releases/`.

13. **Artifact and release management**
   - `releases/version.json` and `releases/changelog.json` track image versioning and release notes.
   - The final deliverables are the ISO plus supporting metadata, with `logs/`, `cache/`, and `taaos_qemu_disk.qcow2` serving as build/test working state rather than product code.

14. **How to diagram it**
   - A good architecture diagram should show four main zones: repository inputs, Dockerized build system, live image composition, and runtime OS services.
   - The key flows are: package lists and overlays into live-build; optional kernel and bootstrap packages into the image; installer/first-boot scripts into runtime; and release artifacts out to ISO/QEMU/VM validation.

Main entry points: [`build_taaos.sh`](https://github.com/taasezer/taaos/blob/main/build_taaos.sh) (build_taaos.sh), [`config/includes.chroot`](https://github.com/taasezer/taaos/blob/main/config/includes.chroot) (Chroot overlay), [`config/hooks/live`](https://github.com/taasezer/taaos/tree/main/config/hooks/live) (Live hooks), [`config/package-lists`](https://github.com/taasezer/taaos/tree/main/config/package-lists) (Package lists)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_build["Build pipeline"]
  node_build_sh["build.sh<br/>orchestrator<br/>[build.sh]"]
  node_build_taaos_sh["build_taaos.sh<br/>build step<br/>[build_taaos.sh]"]
  node_clean_sh["clean.sh<br/>cleanup<br/>[clean.sh]"]
  node_compile_kernel_sh["compile_kernel.sh<br/>kernel build<br/>[compile_kernel.sh]"]
  node_init_config_sh["init_config.sh<br/>init setup<br/>[init_config.sh]"]
  node_dockerfile["Dockerfile<br/>builder image"]
  node_bootstrap_cache[("Bootstrap cache<br/>offline deb cache<br/>[packages.bootstrap]")]
end

subgraph group_image["Live image composition"]
  node_package_lists["Package lists<br/>live-build inputs"]
  node_chroot_packages[("Pinned debs<br/>kernel/package pins<br/>[packages.chroot]")]
  node_binary_includes["Binary media<br/>boot media assets<br/>[includes.binary]"]
  node_hooks["Live hooks<br/>image hooks"]
  node_includes_chroot["Chroot overlay<br/>rootfs overlay<br/>[includes.chroot]"]
  node_bootloaders["Bootloaders<br/>boot config"]
end

subgraph group_runtime["Runtime OS"]
  node_first_boot["First boot<br/>systemd setup"]
  node_update_service["Update service<br/>maintenance"]
  node_calamares["Calamares<br/>installer boundary<br/>[settings.conf]"]
  node_xfce_ux["XFCE UX<br/>desktop customization<br/>[xfce4-panel.xml]"]
  node_sys_hardening["Hardening<br/>security config"]
  node_runtime_tools["TaaOS tools<br/>user utilities<br/>[taaos-help]"]
end

subgraph group_delivery["Validation and release"]
  node_versioning["Release metadata<br/>version files<br/>[version.json]"]
  node_validation_tests["VM tests<br/>smoke tests<br/>[launch_qemu_vm.ps1]"]
end

node_build_sh -->|"cleans"| node_clean_sh
node_build_sh -->|"builds container"| node_dockerfile
node_build_sh -->|"delegates"| node_build_taaos_sh
node_build_taaos_sh -->|"prepares"| node_init_config_sh
node_build_taaos_sh -->|"packages kernel"| node_compile_kernel_sh
node_build_taaos_sh -->|"seeds packages"| node_bootstrap_cache
node_build_taaos_sh -->|"feeds"| node_package_lists
node_build_taaos_sh -->|"runs hooks"| node_hooks
node_build_taaos_sh -->|"lays down"| node_includes_chroot
node_build_taaos_sh -->|"stages media"| node_binary_includes
node_build_taaos_sh -->|"boots"| node_bootloaders
node_build_taaos_sh -->|"outputs"| node_validation_tests
node_hooks -->|"installs"| node_chroot_packages
node_hooks -->|"configures installer"| node_calamares
node_hooks -->|"brands desktop"| node_xfce_ux
node_hooks -->|"hardens"| node_sys_hardening
node_hooks -->|"installs tools"| node_runtime_tools
node_includes_chroot -->|"enables"| node_first_boot
node_includes_chroot -->|"schedules"| node_update_service
node_includes_chroot -->|"contains"| node_runtime_tools
node_includes_chroot -->|"contains"| node_xfce_ux
node_includes_chroot -->|"contains"| node_sys_hardening
node_includes_chroot -->|"contains"| node_calamares
node_package_lists -->|"selects"| node_calamares
node_package_lists -->|"selects desktop"| node_xfce_ux
node_package_lists -->|"selects tools"| node_runtime_tools
node_bootloaders -->|"booted by"| node_validation_tests
node_versioning -->|"tags"| node_build_taaos_sh
node_versioning -->|"tracks"| node_validation_tests

click node_build_sh "https://github.com/taasezer/taaos/blob/main/build.sh"
click node_build_taaos_sh "https://github.com/taasezer/taaos/blob/main/build_taaos.sh"
click node_clean_sh "https://github.com/taasezer/taaos/blob/main/clean.sh"
click node_compile_kernel_sh "https://github.com/taasezer/taaos/blob/main/compile_kernel.sh"
click node_init_config_sh "https://github.com/taasezer/taaos/blob/main/init_config.sh"
click node_dockerfile "https://github.com/taasezer/taaos/tree/main/docker/Dockerfile"
click node_bootstrap_cache "https://github.com/taasezer/taaos/blob/main/cache/packages.bootstrap"
click node_package_lists "https://github.com/taasezer/taaos/tree/main/config/package-lists"
click node_chroot_packages "https://github.com/taasezer/taaos/blob/main/config/packages.chroot"
click node_binary_includes "https://github.com/taasezer/taaos/blob/main/config/includes.binary"
click node_hooks "https://github.com/taasezer/taaos/tree/main/config/hooks/live"
click node_includes_chroot "https://github.com/taasezer/taaos/blob/main/config/includes.chroot"
click node_bootloaders "https://github.com/taasezer/taaos/tree/main/config/bootloaders"
click node_versioning "https://github.com/taasezer/taaos/blob/main/releases/version.json"
click node_validation_tests "https://github.com/taasezer/taaos/blob/main/tests/launch_qemu_vm.ps1"
click node_first_boot "https://github.com/taasezer/taaos/blob/main/config/includes.chroot/etc/systemd/system/taaos-first-boot.service"
click node_update_service "https://github.com/taasezer/taaos/blob/main/config/includes.chroot/etc/systemd/system/taaos-update.service"
click node_calamares "https://github.com/taasezer/taaos/blob/main/config/includes.chroot/etc/calamares/settings.conf"
click node_xfce_ux "https://github.com/taasezer/taaos/blob/main/config/includes.chroot/etc/skel/.config/xfce4/xfconf/xfce-perchannel-xml/xfce4-panel.xml"
click node_sys_hardening "https://github.com/taasezer/taaos/blob/main/config/includes.chroot/etc/sysctl.d/99-taaos-security.conf"
click node_runtime_tools "https://github.com/taasezer/taaos/blob/main/config/includes.chroot/usr/local/bin/taaos-help"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_build_sh,node_build_taaos_sh,node_clean_sh,node_compile_kernel_sh,node_init_config_sh,node_dockerfile,node_bootstrap_cache toneBlue
class node_package_lists,node_chroot_packages,node_binary_includes,node_hooks,node_includes_chroot,node_bootloaders toneAmber
class node_first_boot,node_update_service,node_calamares,node_xfce_ux,node_sys_hardening,node_runtime_tools toneMint
class node_versioning,node_validation_tests toneRose
```

## Components

### Build pipeline

Dockerized orchestration that produces the live image and installer artifacts.

- [build.sh](https://github.com/taasezer/taaos/blob/main/build.sh): orchestrator · Main entrypoint that coordinates cleanup, container setup, and image builds. · `build.sh`
- [build_taaos.sh](https://github.com/taasezer/taaos/blob/main/build_taaos.sh): build step · Secondary build driver used by the orchestration flow. · `build_taaos.sh`
- [clean.sh](https://github.com/taasezer/taaos/blob/main/clean.sh): cleanup · Removes prior outputs and resets build state. · `clean.sh`
- [compile_kernel.sh](https://github.com/taasezer/taaos/blob/main/compile_kernel.sh): kernel build · Builds or packages the custom kernel artifacts consumed by the image. · `compile_kernel.sh`
- [init_config.sh](https://github.com/taasezer/taaos/blob/main/init_config.sh): init setup · Bootstraps repository or live-build configuration before image generation. · `init_config.sh`
- [Dockerfile](https://github.com/taasezer/taaos/tree/main/docker/Dockerfile): builder image · Defines the isolated container used for the Debian live-build toolchain. · `docker/Dockerfile`
- [Bootstrap cache](https://github.com/taasezer/taaos/blob/main/cache/packages.bootstrap): offline deb cache · Preseeded package cache used to make builds reproducible and less network-dependent. · `cache/packages.bootstrap`

### Live image composition

Package lists, hooks, overlays, kernel inputs, and boot media definitions.

- [Package lists](https://github.com/taasezer/taaos/tree/main/config/package-lists): live-build inputs · Edition and role package sets for desktop, AI, engineering, recovery, and related flavors. · `config/package-lists`
- [Pinned debs](https://github.com/taasezer/taaos/blob/main/config/packages.chroot): kernel/package pins · Local .deb artifacts injected into the chroot, including the shipped kernel set. · `config/packages.chroot`
- [Binary media](https://github.com/taasezer/taaos/blob/main/config/includes.binary): boot media assets · Files staged onto the ISO or USB side of the image. · `config/includes.binary`
- [Live hooks](https://github.com/taasezer/taaos/tree/main/config/hooks/live): image hooks · Ordered chroot and binary hooks that assemble the distro during live-build. · `config/hooks/live`
- [Chroot overlay](https://github.com/taasezer/taaos/blob/main/config/includes.chroot): rootfs overlay · Runtime filesystem overlay that defines desktop defaults, services, docs, and branded tools. · `config/includes.chroot`
- [Bootloaders](https://github.com/taasezer/taaos/tree/main/config/bootloaders): boot config · GRUB configuration for both EFI and legacy PC boot paths. · `config/bootloaders`

### Runtime OS

Installed system services, user tools, hardening, and maintenance flows.

- [First boot](https://github.com/taasezer/taaos/blob/main/config/includes.chroot/etc/systemd/system/taaos-first-boot.service): systemd setup · Initial setup path that configures drivers, updates, and first-run behavior. · `config/includes.chroot/etc/systemd/system/taaos-first-boot.service`
- [Update service](https://github.com/taasezer/taaos/blob/main/config/includes.chroot/etc/systemd/system/taaos-update.service): maintenance · Timer-driven maintenance and update workflow inside the installed OS. · `config/includes.chroot/etc/systemd/system/taaos-update.service`
- [Calamares](https://github.com/taasezer/taaos/blob/main/config/includes.chroot/etc/calamares/settings.conf): installer boundary · Installer branding, modules, and post-install logic for deploying TaaOS. · `config/includes.chroot/etc/calamares/settings.conf`
- [XFCE UX](https://github.com/taasezer/taaos/blob/main/config/includes.chroot/etc/skel/.config/xfce4/xfconf/xfce-perchannel-xml/xfce4-panel.xml): desktop customization · Desktop, terminal, display manager, wallpaper, and welcome experience settings. · `config/includes.chroot/etc/skel/.config/xfce4/xfconf/xfce-perchannel-xml/xfce4-panel.xml`
- [Hardening](https://github.com/taasezer/taaos/blob/main/config/includes.chroot/etc/sysctl.d/99-taaos-security.conf): security config · SSH, sysctl, systemd boot tuning, and shell-level hardening for the image. · `config/includes.chroot/etc/sysctl.d/99-taaos-security.conf`
- [TaaOS tools](https://github.com/taasezer/taaos/blob/main/config/includes.chroot/usr/local/bin/taaos-help): user utilities · Branded scripts and helpers for help, diagnostics, cleanup, rescue, and updates. · `config/includes.chroot/usr/local/bin/taaos-help`

### Validation and release

Post-build smoke tests and release metadata.

- [Release metadata](https://github.com/taasezer/taaos/blob/main/releases/version.json): version files · Version and changelog state carried into builds and published artifacts. · `releases/version.json`
- [VM tests](https://github.com/taasezer/taaos/blob/main/tests/launch_qemu_vm.ps1): smoke tests · Boot validation in QEMU and VirtualBox after the image is built. · `tests/launch_qemu_vm.ps1`

## Connections

- build.sh → clean.sh: cleans · Starts from a clean build state before packaging.
- build.sh → Dockerfile: builds container · Uses the Docker image as the isolated build environment.
- build.sh → build_taaos.sh: delegates · Hands off the main build phases to the TaaOS-specific driver.
- build_taaos.sh → init_config.sh: prepares · Initializes live-build and repository configuration.
- build_taaos.sh → compile_kernel.sh: packages kernel · Builds or injects the kernel artifacts used by the image.
- build_taaos.sh → Bootstrap cache: seeds packages · Uses the offline package cache for bootstrap and reproducibility.
- build_taaos.sh → Package lists: feeds · Selects package groups for the target editions.
- build_taaos.sh → Live hooks: runs hooks · Executes live-build hooks to assemble the final filesystem.
- build_taaos.sh → Chroot overlay: lays down · Installs runtime overlay content into the chroot.
- build_taaos.sh → Binary media: stages media · Adds boot-media-only files to the binary output.
- build_taaos.sh → Bootloaders: boots · Includes GRUB configuration for supported boot modes.
- build_taaos.sh → VM tests: outputs · Produces artifacts that are then smoke-tested in VMs.
- Live hooks → Pinned debs: installs · Pulls pinned kernel and local package artifacts into the image.
- Live hooks → Calamares: configures installer · Sets up installer branding and module behavior.
- Live hooks → XFCE UX: brands desktop · Applies desktop defaults and user-experience customization.
- Live hooks → Hardening: hardens · Applies security and boot-time hardening settings.
- Live hooks → TaaOS tools: installs tools · Places the distro-branded runtime utilities into the image.
- Chroot overlay → First boot: enables · Provides the first-boot service and scripts.
- Chroot overlay → Update service: schedules · Installs update timers and maintenance services.
- Chroot overlay → TaaOS tools: contains · Ships the user-facing command suite.
- Chroot overlay → XFCE UX: contains · Defines XFCE and display-manager customization.
- Chroot overlay → Hardening: contains · Carries SSH, sysctl, and systemd hardening snippets.
- Chroot overlay → Calamares: contains · Carries installer configs and post-install logic.
- Package lists → Calamares: selects · Includes installer-related package groups.
- Package lists → XFCE UX: selects desktop · Includes desktop and theme packages that drive the UX layer.
- Package lists → TaaOS tools: selects tools · Includes packages that support the branded utility layer.
- Bootloaders → VM tests: booted by · The produced ISO is validated through VM boot paths.
- Release metadata → build_taaos.sh: tags · Provides release identity for the generated artifact.
- Release metadata → VM tests: tracks · Associates test runs with the release version.
