# sounddrill31/crave_aosp_builder architecture

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

- Interactive diagram: https://gitdiagram.com/sounddrill31/crave_aosp_builder
- Repository: https://github.com/sounddrill31/crave_aosp_builder

## Overview

##### Project type and purpose
- This is a CI/CD-style tooling repository (“crave_aosp_builder”) built around GitHub Actions.
- Its purpose is to orchestrate Android OS builds on external build servers (Crave.io) or on your own self-hosted runners, with optional integrations (code-server remote IDE, Telegram notifications, GitHub Releases, Backblaze B2 signing).

##### File structure
- Top-level:
- `.github/workflows/` – multiple workflow YAMLs: configure self-hosted runner, start/restart it, and the main build pipelines.
- `configs/` – templates for code-server and Crave CLI (`crave.yaml.*`).
- `scripts/` – bash scripts for environment checks, runner setup, code-server launch, VSCode tunneling.
- `assets/` – documentation images (secrets setup, runner token flow).
- `README.md` & sample `crave.conf.sample` – detailed usage and config reference.
- No “frontend” or “backend” per se; instead it’s an “automation orchestration” project.

##### README for architecture clues
- Describes workflows dispatch, required secrets (CRAVE_USERNAME, CRAVE_TOKEN, optional TELEGRAM_TOKEN, etc.).
- Two modes: GitHub-hosted runners (6h timeout, more Action abuse risk) vs self-hosted runners (persist beyond timeouts).
- External dependencies: Crave.io build servers, optional Backblaze B2, Telegram Bot API, GitHub Releases API.

##### Elements
- Labels: e.g., “GitHub Repository”, “GitHub Actions”, “Self-Hosted Runner”, “Crave Build Service”, “Artifact Storage”
- from Repo → Actions → Runner
- from Runner ↔ Crave.io
- from Runner → GitHub Releases / Telegram API / Backblaze B2
- Orange clouds for external services (Crave.io, Telegram, Backblaze)

##### Final advice
- Be very detailed: break the runner node into sub-components (setup scripts, code-server, env checker).
- Optional paths (e.g., signing, custom YAML override).
- Secrets as configuration inputs.

## Diagram (Mermaid)

```mermaid
graph TB
  classDef internal fill:#D0E8FF,stroke:#000
  classDef external fill:#FFD0A8,stroke:#000
  classDef storage fill:#D0FFD0,stroke:#000

  subgraph "GitHub Repository"
    Repo["GitHub Repository"]:::internal
    subgraph "Contents"
      Workflows["Workflow Definitions"]:::internal
      Assets["Assets"]:::internal
      Readme["README.md"]:::internal
    end
  end

  click Workflows "https://github.com/sounddrill31/crave_aosp_builder/tree/main/.github/workflows/"
  click Assets "https://github.com/sounddrill31/crave_aosp_builder/tree/main/assets/"
  click Readme "https://github.com/sounddrill31/crave_aosp_builder/blob/main/README.md"

  subgraph "GitHub Actions Orchestrator"
    CfgRunner["Configure Runner Workflow"]:::internal
    SelfHostWF["Self-Hosted Runner Workflow"]:::internal
    RestartWF["Restart Runner Workflow"]:::internal
  end

  click CfgRunner "https://github.com/sounddrill31/crave_aosp_builder/blob/main/.github/workflows/configure-runner.yml"
  click SelfHostWF "https://github.com/sounddrill31/crave_aosp_builder/blob/main/.github/workflows/selfhosted.yml"
  click RestartWF "https://github.com/sounddrill31/crave_aosp_builder/blob/main/.github/workflows/force-restart-runner.yml"

  subgraph "Runner Compute Layer"
    GitHubHosted["GitHub-Hosted Runner"]:::internal
    subgraph "Self-Hosted Runner"
      RunnerSetup["Runner Setup & Env Check"]:::internal
      CodeServerCFG["code-server Config"]:::internal
      CodeServerScript["code-server Launch Script"]:::internal
      VSCodeTunnel["VSCode Tunnel Script"]:::internal
    end
  end

  click RunnerSetup "https://github.com/sounddrill31/crave_aosp_builder/blob/main/scripts/runner-setup.sh"
  click RunnerSetup "https://github.com/sounddrill31/crave_aosp_builder/blob/main/scripts/env-checker.sh"
  click CodeServerCFG "https://github.com/sounddrill31/crave_aosp_builder/blob/main/configs/code-server/config.yaml"
  click CodeServerScript "https://github.com/sounddrill31/crave_aosp_builder/blob/main/scripts/code-server.sh"
  click VSCodeTunnel "https://github.com/sounddrill31/crave_aosp_builder/blob/main/scripts/vscode-tunnel.sh"

  subgraph "Crave.io Build Service"
    CraveCLI["Crave.io Build Service"]:::external
    CraveConfigAOSP["AOSP Config"]:::external
    CraveConfigTWRP["TWRP Config"]:::external
    CraveConfigLegacy["TWRP Legacy Config"]:::external
    CraveSample["crave.conf.sample"]:::external
  end

  click CraveConfigAOSP "https://github.com/sounddrill31/crave_aosp_builder/blob/main/configs/crave/crave.yaml.aosp"
  click CraveConfigTWRP "https://github.com/sounddrill31/crave_aosp_builder/blob/main/configs/crave/crave.yaml.twrp"
  click CraveConfigLegacy "https://github.com/sounddrill31/crave_aosp_builder/blob/main/configs/crave/crave.yaml.twrp.legacy"
  click CraveSample "https://github.com/sounddrill31/crave_aosp_builder/blob/main/crave.conf.sample"

  subgraph "Artifact Publishing"
    GitHubRel["GitHub Releases"]:::storage
    Telegram["Telegram Bot API"]:::external
    Backblaze["Backblaze B2 Storage"]:::storage
  end

  %% Connections
  Repo --> Workflows
  Repo --> Assets
  Repo --> Readme

  Workflows --> CfgRunner
  Workflows --> SelfHostWF
  Workflows --> RestartWF

  CfgRunner --> GitHubHosted
  CfgRunner --> RunnerSetup

  SelfHostWF --> RunnerSetup
  RestartWF --> RunnerSetup

  RunnerSetup --> CodeServerCFG
  RunnerSetup --> CodeServerScript
  RunnerSetup --> VSCodeTunnel

  RunnerSetup --> CraveCLI
  CraveCLI --> RunnerSetup

  RunnerSetup --> GitHubRel
  RunnerSetup --> Telegram
  RunnerSetup --> Backblaze
```
