# octosense-org/octosense-rom architecture

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

- Interactive diagram: https://gitdiagram.com/octosense-org/octosense-rom
- Repository: https://github.com/octosense-org/octosense-rom

## Overview

OctoSense combines an installable Android Home launcher, bundled apps and device services, privileged ROM integrations, and a browser-based ROM installer. The main Home runtime hosts app modules or child processes; the Android bridge provides authorized device and notification operations, while ROM builds add Quickstep and SystemUI behavior. The graph retains README-level capabilities even where their implementation was not sampled; arrows are limited to documented product flows and calls visible in sampled source.

Main entry points: [`home/src/apps.rs`](https://github.com/octosense-org/octosense-rom/blob/main/home/src/apps.rs) (App hosting), [`home/android/system-bridge/src/main/java/dev/makepad/octosense/bridge/SystemBridgeService.java`](https://github.com/octosense-org/octosense-rom/blob/main/home/android/system-bridge/src/main/java/dev/makepad/octosense/bridge/SystemBridgeService.java) (Bridge API), [`home/src/main.rs`](https://github.com/octosense-org/octosense-rom/blob/main/home/src/main.rs) (Home runtime), [`home/android/system-bridge/src/main/java/dev/makepad/octosense/bridge/BridgeState.java`](https://github.com/octosense-org/octosense-rom/blob/main/home/android/system-bridge/src/main/java/dev/makepad/octosense/bridge/BridgeState.java) (Bridge state)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_home["Home launcher"]
  node_home_runtime["Home runtime<br/>[main.rs]"]
  node_launcher["Launcher shell<br/>[launcher.rs]"]
  node_notifications["Notifications<br/>[notifications.rs]"]
  node_app_hub["App Hub<br/>[hub.rs]"]
  node_hosting["App hosting<br/>[apps.rs]"]
end

subgraph group_apps["Bundled apps"]
  node_maps["Maps app<br/>[view.rs]"]
  node_news["News app<br/>[view.rs]"]
  node_photos["Photos app<br/>[ui.rs]"]
  node_reference["Reference app<br/>[lib.rs]"]
end

subgraph group_bridge["Android services"]
  node_bridge_api["Bridge API"]
  node_bridge_state["Bridge state<br/>[BridgeState.java]"]
  node_root_service["Scoped root"]
  node_notification_access["Notification access"]
end

subgraph group_rom["ROM integrations"]
  node_quickstep["Quickstep integration"]
  node_home_transitions["Home transitions"]
  node_global_shade["Global shade"]
  node_systemui_tile["SystemUI tile<br/>[OctoSenseTile.java]"]
end

subgraph group_installer["ROM installer"]
  node_installer_ui["Installer UI<br/>[app.mjs]"]
  node_install_session["Install session<br/>[session.mjs]"]
  node_manifest["Release manifest<br/>[contracts.mjs]"]
  node_staging["Release staging<br/>[staging.mjs]"]
  node_transport["Fastboot transport<br/>[transport.mjs]"]
end

node_person(("Phone user"))
node_phone(("Android phone"))
node_release_source["ROM release"]

node_person -->|"opens"| node_launcher
node_launcher -->|"dispatches"| node_home_runtime
node_home_runtime -->|"resolves hosting"| node_hosting
node_hosting -->|"hosts module"| node_maps
node_hosting -->|"hosts module"| node_news
node_hosting -->|"hosts module"| node_photos
node_hosting -->|"hosts module"| node_reference
node_person -->|"browses apps"| node_app_hub
node_person -->|"manages"| node_notifications
node_notifications -->|"commands"| node_bridge_api
node_home_runtime -->|"requests services"| node_bridge_api
node_bridge_api -->|"dispatches"| node_bridge_state
node_bridge_state -->|"requests privileged controls"| node_root_service
node_bridge_state -->|"accesses notifications"| node_notification_access
node_quickstep -->|"subscribes"| node_bridge_api
node_global_shade -->|"subscribes"| node_bridge_api
node_quickstep -->|"begins transitions"| node_home_transitions
node_systemui_tile -->|"opens shade"| node_global_shade
node_person -->|"starts install"| node_installer_ui
node_installer_ui -->|"drives"| node_install_session
node_installer_ui -->|"loads manifest"| node_manifest
node_install_session -->|"prepares release"| node_staging
node_install_session -->|"communicates"| node_transport
node_staging -->|"downloads release"| node_release_source
node_transport -->|"reads and flashes"| node_phone

click node_home_runtime "https://github.com/octosense-org/octosense-rom/blob/main/home/src/main.rs"
click node_launcher "https://github.com/octosense-org/octosense-rom/blob/main/home/src/shell/launcher.rs"
click node_notifications "https://github.com/octosense-org/octosense-rom/blob/main/home/src/shell/notifications.rs"
click node_app_hub "https://github.com/octosense-org/octosense-rom/blob/main/home/src/hub.rs"
click node_hosting "https://github.com/octosense-org/octosense-rom/blob/main/home/src/apps.rs"
click node_maps "https://github.com/octosense-org/octosense-rom/blob/main/home/apps/maps/src/view.rs"
click node_news "https://github.com/octosense-org/octosense-rom/blob/main/home/apps/news/src/view.rs"
click node_photos "https://github.com/octosense-org/octosense-rom/blob/main/home/apps/photos/src/ui.rs"
click node_reference "https://github.com/octosense-org/octosense-rom/blob/main/home/apps/reference/src/lib.rs"
click node_bridge_api "https://github.com/octosense-org/octosense-rom/blob/main/home/android/system-bridge/src/main/java/dev/makepad/octosense/bridge/SystemBridgeService.java"
click node_bridge_state "https://github.com/octosense-org/octosense-rom/blob/main/home/android/system-bridge/src/main/java/dev/makepad/octosense/bridge/BridgeState.java"
click node_root_service "https://github.com/octosense-org/octosense-rom/blob/main/home/android/system-bridge/src/main/java/dev/makepad/octosense/bridge/ScopedRootService.java"
click node_notification_access "https://github.com/octosense-org/octosense-rom/blob/main/home/android/system-bridge/src/main/java/dev/makepad/octosense/bridge/NotificationAccessService.java"
click node_quickstep "https://github.com/octosense-org/octosense-rom/blob/main/home/android/quickstep/src/main/java/dev/makepad/octosense/quickstep/HomeIntegrationService.java"
click node_home_transitions "https://github.com/octosense-org/octosense-rom/blob/main/home/android/quickstep/src/main/java/dev/makepad/octosense/quickstep/HomeTransitions.java"
click node_global_shade "https://github.com/octosense-org/octosense-rom/blob/main/home/android/platform-build/quickstep/java/dev/makepad/octosense/quickstep/GlobalShadeController.java"
click node_systemui_tile "https://github.com/octosense-org/octosense-rom/blob/main/home/android/platform-build/systemui/files/src/com/android/systemui/octosense/OctoSenseTile.java"
click node_installer_ui "https://github.com/octosense-org/octosense-rom/blob/main/web-installer/src/app.mjs"
click node_install_session "https://github.com/octosense-org/octosense-rom/blob/main/web-installer/src/session.mjs"
click node_manifest "https://github.com/octosense-org/octosense-rom/blob/main/web-installer/src/contracts.mjs"
click node_staging "https://github.com/octosense-org/octosense-rom/blob/main/web-installer/src/staging.mjs"
click node_transport "https://github.com/octosense-org/octosense-rom/blob/main/web-installer/src/transport.mjs"

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_home_runtime,node_launcher,node_notifications,node_app_hub,node_hosting,node_person toneBlue
class node_maps,node_news,node_photos,node_reference toneAmber
class node_bridge_api,node_bridge_state,node_root_service,node_notification_access toneMint
class node_quickstep,node_home_transitions,node_global_shade,node_systemui_tile toneRose
class node_installer_ui,node_install_session,node_manifest,node_staging,node_transport,node_phone,node_release_source toneIndigo
```

## Components

### Home launcher

- [Home runtime](https://github.com/octosense-org/octosense-rom/blob/main/home/src/main.rs): `home/src/main.rs`
- [Launcher shell](https://github.com/octosense-org/octosense-rom/blob/main/home/src/shell/launcher.rs): `home/src/shell/launcher.rs`
- [Notifications](https://github.com/octosense-org/octosense-rom/blob/main/home/src/shell/notifications.rs): `home/src/shell/notifications.rs`
- [App Hub](https://github.com/octosense-org/octosense-rom/blob/main/home/src/hub.rs): `home/src/hub.rs`
- [App hosting](https://github.com/octosense-org/octosense-rom/blob/main/home/src/apps.rs): `home/src/apps.rs`

### Bundled apps

- [Maps app](https://github.com/octosense-org/octosense-rom/blob/main/home/apps/maps/src/view.rs): `home/apps/maps/src/view.rs`
- [News app](https://github.com/octosense-org/octosense-rom/blob/main/home/apps/news/src/view.rs): `home/apps/news/src/view.rs`
- [Photos app](https://github.com/octosense-org/octosense-rom/blob/main/home/apps/photos/src/ui.rs): `home/apps/photos/src/ui.rs`
- [Reference app](https://github.com/octosense-org/octosense-rom/blob/main/home/apps/reference/src/lib.rs): `home/apps/reference/src/lib.rs`

### Android services

- [Bridge API](https://github.com/octosense-org/octosense-rom/blob/main/home/android/system-bridge/src/main/java/dev/makepad/octosense/bridge/SystemBridgeService.java): `home/android/system-bridge/src/main/java/dev/makepad/octosense/bridge/SystemBridgeService.java`
- [Bridge state](https://github.com/octosense-org/octosense-rom/blob/main/home/android/system-bridge/src/main/java/dev/makepad/octosense/bridge/BridgeState.java): `home/android/system-bridge/src/main/java/dev/makepad/octosense/bridge/BridgeState.java`
- [Scoped root](https://github.com/octosense-org/octosense-rom/blob/main/home/android/system-bridge/src/main/java/dev/makepad/octosense/bridge/ScopedRootService.java): `home/android/system-bridge/src/main/java/dev/makepad/octosense/bridge/ScopedRootService.java`
- [Notification access](https://github.com/octosense-org/octosense-rom/blob/main/home/android/system-bridge/src/main/java/dev/makepad/octosense/bridge/NotificationAccessService.java): `home/android/system-bridge/src/main/java/dev/makepad/octosense/bridge/NotificationAccessService.java`

### ROM integrations

- [Quickstep integration](https://github.com/octosense-org/octosense-rom/blob/main/home/android/quickstep/src/main/java/dev/makepad/octosense/quickstep/HomeIntegrationService.java): `home/android/quickstep/src/main/java/dev/makepad/octosense/quickstep/HomeIntegrationService.java`
- [Home transitions](https://github.com/octosense-org/octosense-rom/blob/main/home/android/quickstep/src/main/java/dev/makepad/octosense/quickstep/HomeTransitions.java): `home/android/quickstep/src/main/java/dev/makepad/octosense/quickstep/HomeTransitions.java`
- [Global shade](https://github.com/octosense-org/octosense-rom/blob/main/home/android/platform-build/quickstep/java/dev/makepad/octosense/quickstep/GlobalShadeController.java): `home/android/platform-build/quickstep/java/dev/makepad/octosense/quickstep/GlobalShadeController.java`
- [SystemUI tile](https://github.com/octosense-org/octosense-rom/blob/main/home/android/platform-build/systemui/files/src/com/android/systemui/octosense/OctoSenseTile.java): `home/android/platform-build/systemui/files/src/com/android/systemui/octosense/OctoSenseTile.java`

### ROM installer

- [Installer UI](https://github.com/octosense-org/octosense-rom/blob/main/web-installer/src/app.mjs): `web-installer/src/app.mjs`
- [Install session](https://github.com/octosense-org/octosense-rom/blob/main/web-installer/src/session.mjs): `web-installer/src/session.mjs`
- [Release manifest](https://github.com/octosense-org/octosense-rom/blob/main/web-installer/src/contracts.mjs): `web-installer/src/contracts.mjs`
- [Release staging](https://github.com/octosense-org/octosense-rom/blob/main/web-installer/src/staging.mjs): `web-installer/src/staging.mjs`
- [Fastboot transport](https://github.com/octosense-org/octosense-rom/blob/main/web-installer/src/transport.mjs): `web-installer/src/transport.mjs`

### Other components

- **Phone user**
- **Android phone**
- **ROM release**

## Connections

- Phone user → Launcher shell: opens
- Launcher shell → Home runtime: dispatches
- Home runtime → App hosting: resolves hosting
- App hosting → Maps app: hosts module
- App hosting → News app: hosts module
- App hosting → Photos app: hosts module
- App hosting → Reference app: hosts module
- Phone user → App Hub: browses apps
- Phone user → Notifications: manages
- Notifications → Bridge API: commands
- Home runtime → Bridge API: requests services
- Bridge API → Bridge state: dispatches
- Bridge state → Scoped root: requests privileged controls
- Bridge state → Notification access: accesses notifications
- Quickstep integration → Bridge API: subscribes
- Global shade → Bridge API: subscribes
- Quickstep integration → Home transitions: begins transitions
- SystemUI tile → Global shade: opens shade
- Phone user → Installer UI: starts install
- Installer UI → Install session: drives
- Installer UI → Release manifest: loads manifest
- Install session → Release staging: prepares release
- Install session → Fastboot transport: communicates
- Release staging → ROM release: downloads release
- Fastboot transport → Android phone: reads and flashes