# ethanarbuckle/carplay-cast architecture

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

- Interactive diagram: https://gitdiagram.com/ethanarbuckle/carplay-cast
- Repository: https://github.com/ethanarbuckle/carplay-cast

## Overview

##### Project Type & Purpose
- This is an iOS jailbreak tweak (“carplay-cast”) that hooks into SpringBoard/CarPlay/UIApplication processes to enable any app on CarPlay (iOS 14+).
- It includes:
- A Theos build system for compiling Objective-C++/logos hooks
- A Preference pane bundle for Settings
- Debian packaging metadata & a repo uploader script
- A Python Cloud Function for crash reporting
- End-to-end tests (Cypress)
- GitHub Actions for CI

##### High-Level Components
A. Developer & CI Environment
- Source code (src/, carplayenableprefs/, control, Makefile)
- .github/workflows/c-cpp.yml (build & test)
- tests/*.cy (Cypress E2E tests)
B. Packaging & Distribution
- control, postinst_postrm, repo/push_deb_to_repo.py
- Debian repo (repo/Release)
C. Device Runtime (Jailbroken iOS)
- Tweak injection into:
– SpringBoard (hooks/SpringBoard.xm)
– CarPlay daemon (hooks/CarPlay.xm)
– UIApplication (hooks/UIApplication.xm)
- Core logic (src/CRCarplayWindow.mm, src/CRPreferences.mm, src/common.h)
- Preference bundle (carplayenableprefs/)
D. Crash-Reporting Backend
- Cloud Function (crash_reporting_cloud_function/main.py, tasks.py)
- Requirements, Pipfile, log_browser.py
- External storage or Pub/Sub (implicit)

##### Interactions & Data Flows
1. Developer commits → GitHub Actions builds & runs Cypress tests → produces .deb
2. push_deb_to_repo.py uploads .deb to package repo
3. User on jailbroken device installs .deb from repo
4. Tweak code hooks into system processes at runtime
5. If a crash occurs, reporting.mm captures stack trace & POSTs to Cloud Function endpoint
6. Cloud Function processes & stores logs; log_browser.py fetches them for review

##### Architectural Patterns & Principles
- Modular Theos project: separate hook libraries, common code, preference UI
- Debian packaging for distribution via APT repo
- Serverless crash reporting (event-driven Cloud Function)
- CI/CD with GitHub Actions
- E2E automated testing (Cypress)

## Diagram (Mermaid)

```mermaid
graph TB
    %% Developer & CI Environment
    subgraph "Developer & CI Environment"
        direction TB
        DevSource["Source Code (src/)"]:::build
        PrefPaneSrc["Preference Pane Source (carplayenableprefs/)"]:::build
        TheosBuild["Theos Build Files (Makefile, control)"]:::build
        CIWorkflow["CI Workflow (.github/workflows/c-cpp.yml)"]:::build
        subgraph "End-to-End Tests"
            direction TB
            Test1["carplay_tests.cy"]:::tests
            Test2["springboard_tests.cy"]:::tests
        end
        BuildDeb["Build .deb"]:::build
    end

    %% Packaging & Distribution
    subgraph "Packaging & Distribution"
        direction TB
        DebMeta["Debian Metadata (control, postinst_postrm)"]:::packaging
        RepoScript["Repo Uploader (push_deb_to_repo.py)"]:::script
        RepoIndex["Debian Repo Index (Release)"]:::packaging
    end

    %% Device Runtime (Jailbroken iOS)
    subgraph "Device Runtime (Jailbroken iOS)"
        direction TB
        UserInstall["User installs .deb"]:::device
        subgraph "Hook Modules"
            direction TB
            HookSB["SpringBoard Hook"]:::device
            HookCP["CarPlay Hook"]:::device
            HookUI["UIApplication Hook"]:::device
        end
        subgraph "Core Logic Library"
            direction TB
            Core1["CRCarplayWindow.mm"]:::device
            Core2["CRPreferences.mm"]:::device
            Core3["common.h"]:::device
        end
        PrefBundle["Preference Bundle"]:::device
        CrashCap["Crash Capturer"]:::device
    end

    %% Crash-Reporting Backend
    subgraph "Crash-Reporting Backend"
        direction TB
        CFMain["Cloud Function (main.py)"]:::cloud
        CFTasks["Tasks (tasks.py)"]:::cloud
        CFPipfile["Pipfile"]:::cloud
        CFReq["requirements.txt"]:::cloud
        LogBrowser["Log Browser (log_browser.py)"]:::script
        External["External Storage / Pub/Sub"]:::cloud
    end

    %% Connections
    DevSource -->|compile| BuildDeb
    PrefPaneSrc -->|include in build| BuildDeb
    TheosBuild -->|invoke Makefile| BuildDeb
    CIWorkflow -->|trigger build & tests| BuildDeb
    Test1 -->|pass| BuildDeb
    Test2 -->|pass| BuildDeb

    BuildDeb -->|upload package| RepoScript
    RepoScript -->|update repo| RepoIndex

    RepoIndex -->|APT install| UserInstall

    UserInstall -->|hook injection| HookSB
    UserInstall -->|hook injection| HookCP
    UserInstall -->|hook injection| HookUI

    HookSB -->|calls common| Core1
    HookCP -->|calls common| Core1
    HookUI -->|calls common| Core1
    Core1 --> Core2
    Core2 --> Core3

    HookSB -->|UI prefs| PrefBundle
    HookCP -->|UI prefs| PrefBundle
    HookUI -->|UI prefs| PrefBundle

    Core1 -->|on crash| CrashCap
    CrashCap -->|POST crash log| CFMain
    CFMain -->|store logs| External
    CFTasks -->|manage events| External
    LogBrowser -->|fetch logs| External

    %% Click Events
    click DevSource "https://github.com/ethanarbuckle/carplay-cast/tree/master/src/"
    click PrefPaneSrc "https://github.com/ethanarbuckle/carplay-cast/tree/master/carplayenableprefs/"
    click TheosBuild "https://github.com/ethanarbuckle/carplay-cast/tree/master/Makefile"
    click TheosBuild "https://github.com/ethanarbuckle/carplay-cast/tree/master/control"
    click CIWorkflow "https://github.com/ethanarbuckle/carplay-cast/blob/master/.github/workflows/c-cpp.yml"
    click Test1 "https://github.com/ethanarbuckle/carplay-cast/blob/master/tests/carplay_tests.cy"
    click Test2 "https://github.com/ethanarbuckle/carplay-cast/blob/master/tests/springboard_tests.cy"
    click DebMeta "https://github.com/ethanarbuckle/carplay-cast/tree/master/control"
    click DebMeta "https://github.com/ethanarbuckle/carplay-cast/tree/master/postinst_postrm"
    click RepoScript "https://github.com/ethanarbuckle/carplay-cast/blob/master/repo/push_deb_to_repo.py"
    click RepoIndex "https://github.com/ethanarbuckle/carplay-cast/tree/master/repo/Release"
    click HookSB "https://github.com/ethanarbuckle/carplay-cast/blob/master/src/hooks/SpringBoard.xm"
    click HookCP "https://github.com/ethanarbuckle/carplay-cast/blob/master/src/hooks/CarPlay.xm"
    click HookUI "https://github.com/ethanarbuckle/carplay-cast/blob/master/src/hooks/UIApplication.xm"
    click Core1 "https://github.com/ethanarbuckle/carplay-cast/blob/master/src/CRCarplayWindow.mm"
    click Core2 "https://github.com/ethanarbuckle/carplay-cast/blob/master/src/CRPreferences.mm"
    click Core3 "https://github.com/ethanarbuckle/carplay-cast/blob/master/src/common.h"
    click PrefBundle "https://github.com/ethanarbuckle/carplay-cast/tree/master/carplayenableprefs/"
    click CFMain "https://github.com/ethanarbuckle/carplay-cast/blob/master/crash_reporting_cloud_function/main.py"
    click CFTasks "https://github.com/ethanarbuckle/carplay-cast/blob/master/crash_reporting_cloud_function/tasks.py"
    click CFPipfile "https://github.com/ethanarbuckle/carplay-cast/tree/master/crash_reporting_cloud_function/Pipfile"
    click CFReq "https://github.com/ethanarbuckle/carplay-cast/blob/master/crash_reporting_cloud_function/requirements.txt"
    click LogBrowser "https://github.com/ethanarbuckle/carplay-cast/blob/master/crash_reporting_cloud_function/log_browser.py"

    %% Styles
    classDef build fill:#D0E1FF,stroke:#0366d6,color:#000
    classDef packaging fill:#FFF5CE,stroke:#cfa20a,color:#000
    classDef device fill:#D6FFE0,stroke:#2c8a1f,color:#000
    classDef cloud fill:#FFE0B2,stroke:#e65100,color:#000
    classDef script fill:#FFD6E8,stroke:#c2185b,color:#000
    classDef tests fill:#E8E8E8,stroke:#555,color:#000
```
