# simplyluma/luma architecture

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

- Interactive diagram: https://gitdiagram.com/simplyluma/luma
- Repository: https://github.com/simplyluma/luma

## Overview

Luma is an operating system and shared application platform. Its principal user journey is to install the OS, then use bundled applications and desktop services through a common adaptive UI; the update agent manages later system updates. The README also identifies Android compatibility, external app integrations, and device-specific profiles as meaningful branches. The graph combines those documented capabilities with sampled implementation modules; some subsystem links are therefore documented rather than traced through unsampled code.

Main entry points: [`src/prairie-core`](https://github.com/simplyluma/luma/tree/main/src/prairie-core) (Shared Applications), [`src/luma-installer-atlas/src/hooks/Storage.jsx`](https://github.com/simplyluma/luma/blob/main/src/luma-installer-atlas/src/hooks/Storage.jsx) (Atlas Installer), [`extensions`](https://github.com/simplyluma/luma/tree/main/extensions) (Desktop Shell), [`image`](https://github.com/simplyluma/luma/tree/main/image) (Luma OS)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_platform["Shared Platform"]
  node_sdk["Application Kit"]
  node_portal["Application Portals<br/>[apps.py]"]
end

subgraph group_apps["Bundled Applications"]
  node_apps["Shared Applications"]
  node_disks["Disks App<br/>[app.py]"]
  node_charlie["Charlie Mail<br/>[model.py]"]
  node_viola["Viola Browser"]
end

subgraph group_system["OS Services"]
  node_shell["Desktop Shell"]
  node_background["Background Manager<br/>[manager.py]"]
  node_energy["Energy Manager<br/>[manager.py]"]
  node_tester["Luma Tester<br/>[core.py]"]
end

subgraph group_lifecycle["Install and Updates"]
  node_installer["Atlas Installer<br/>[Storage.jsx]"]
  node_storage["Storage Planning"]
  node_os["Luma OS"]
  node_updater["Update Agent<br/>[engine.py]"]
end

subgraph group_integrations["Integrations"]
  node_android["Android Compatibility<br/>[engine.py]"]
  node_androidkernel["Android Kernel Layer<br/>[kernel.py]"]
  node_devices["Device Profiles"]
  node_continuity["Continuity<br/>[application.py]"]
  node_relay["Windows App Relay<br/>[engine.py]"]
end

node_user(("User"))

node_user -->|"installs through"| node_installer
node_installer -->|"requests partitioning"| node_storage
node_installer -.->|"installs"| node_os
node_os -.->|"receives updates"| node_updater
node_user -->|"uses"| node_apps
node_apps -->|"uses shared platform"| node_sdk
node_apps -->|"uses portals"| node_portal
node_user -.->|"manages disks"| node_disks
node_user -->|"uses mail"| node_charlie
node_user -->|"uses browser"| node_viola
node_user -->|"interacts with"| node_shell
node_shell -->|"offers compatibility"| node_android
node_android -->|"uses kernel support"| node_androidkernel
node_user -.->|"controls background apps"| node_background
node_user -.->|"uses power services"| node_energy
node_user -.->|"qualifies images"| node_tester
node_user -->|"uses supported profiles"| node_devices
node_user -.->|"uses continuity"| node_continuity
node_user -.->|"runs Windows apps"| node_relay

click node_installer "https://github.com/simplyluma/luma/blob/main/src/luma-installer-atlas/src/hooks/Storage.jsx"
click node_storage "https://github.com/simplyluma/luma/blob/main/src/luma-installer-atlas/src/apis/storage_partitioning.js"
click node_os "https://github.com/simplyluma/luma/tree/main/image"
click node_updater "https://github.com/simplyluma/luma/blob/main/src/luma-update/luma_update/engine.py"
click node_sdk "https://github.com/simplyluma/luma/tree/main/src/luma-platform/appkit/luma_appkit"
click node_portal "https://github.com/simplyluma/luma/blob/main/src/luma-platform/portal/luma_portal/apps.py"
click node_apps "https://github.com/simplyluma/luma/tree/main/src/prairie-core"
click node_disks "https://github.com/simplyluma/luma/blob/main/src/luma-disks/luma_disks/app.py"
click node_charlie "https://github.com/simplyluma/luma/blob/main/src/external/charlie/charlie_luma/model.py"
click node_viola "https://github.com/simplyluma/luma/tree/main/src/external/viola/chromium-linux/appkit-spike"
click node_shell "https://github.com/simplyluma/luma/tree/main/extensions"
click node_background "https://github.com/simplyluma/luma/blob/main/src/luma-background/luma_background/manager.py"
click node_energy "https://github.com/simplyluma/luma/blob/main/src/luma-energy/luma_energy/manager.py"
click node_tester "https://github.com/simplyluma/luma/blob/main/src/luma-tester/luma_tester/core.py"
click node_android "https://github.com/simplyluma/luma/blob/main/src/luma-android/luma_android/engine.py"
click node_androidkernel "https://github.com/simplyluma/luma/blob/main/src/luma-android/luma_android/kernel.py"
click node_devices "https://github.com/simplyluma/luma/tree/main/config"
click node_continuity "https://github.com/simplyluma/luma/blob/main/src/luma-continuity/luma_continuity/application.py"
click node_relay "https://github.com/simplyluma/luma/blob/main/src/luma-relay/luma_relay/engine.py"

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_sdk,node_portal,node_user toneBlue
class node_apps,node_disks,node_charlie,node_viola toneAmber
class node_shell,node_background,node_energy,node_tester toneMint
class node_installer,node_storage,node_os,node_updater toneRose
class node_android,node_androidkernel,node_devices,node_continuity,node_relay toneIndigo
```

## Components

### Shared Platform

- [Application Kit](https://github.com/simplyluma/luma/tree/main/src/luma-platform/appkit/luma_appkit): `src/luma-platform/appkit/luma_appkit`
- [Application Portals](https://github.com/simplyluma/luma/blob/main/src/luma-platform/portal/luma_portal/apps.py): `src/luma-platform/portal/luma_portal/apps.py`

### Bundled Applications

- [Shared Applications](https://github.com/simplyluma/luma/tree/main/src/prairie-core): `src/prairie-core`
- [Disks App](https://github.com/simplyluma/luma/blob/main/src/luma-disks/luma_disks/app.py): `src/luma-disks/luma_disks/app.py`
- [Charlie Mail](https://github.com/simplyluma/luma/blob/main/src/external/charlie/charlie_luma/model.py): `src/external/charlie/charlie_luma/model.py`
- [Viola Browser](https://github.com/simplyluma/luma/tree/main/src/external/viola/chromium-linux/appkit-spike): `src/external/viola/chromium-linux/appkit-spike`

### OS Services

- [Desktop Shell](https://github.com/simplyluma/luma/tree/main/extensions): `extensions`
- [Background Manager](https://github.com/simplyluma/luma/blob/main/src/luma-background/luma_background/manager.py): `src/luma-background/luma_background/manager.py`
- [Energy Manager](https://github.com/simplyluma/luma/blob/main/src/luma-energy/luma_energy/manager.py): `src/luma-energy/luma_energy/manager.py`
- [Luma Tester](https://github.com/simplyluma/luma/blob/main/src/luma-tester/luma_tester/core.py): `src/luma-tester/luma_tester/core.py`

### Install and Updates

- [Atlas Installer](https://github.com/simplyluma/luma/blob/main/src/luma-installer-atlas/src/hooks/Storage.jsx): `src/luma-installer-atlas/src/hooks/Storage.jsx`
- [Storage Planning](https://github.com/simplyluma/luma/blob/main/src/luma-installer-atlas/src/apis/storage_partitioning.js): `src/luma-installer-atlas/src/apis/storage_partitioning.js`
- [Luma OS](https://github.com/simplyluma/luma/tree/main/image): `image`
- [Update Agent](https://github.com/simplyluma/luma/blob/main/src/luma-update/luma_update/engine.py): `src/luma-update/luma_update/engine.py`

### Integrations

- [Android Compatibility](https://github.com/simplyluma/luma/blob/main/src/luma-android/luma_android/engine.py): `src/luma-android/luma_android/engine.py`
- [Android Kernel Layer](https://github.com/simplyluma/luma/blob/main/src/luma-android/luma_android/kernel.py): `src/luma-android/luma_android/kernel.py`
- [Device Profiles](https://github.com/simplyluma/luma/tree/main/config): `config`
- [Continuity](https://github.com/simplyluma/luma/blob/main/src/luma-continuity/luma_continuity/application.py): `src/luma-continuity/luma_continuity/application.py`
- [Windows App Relay](https://github.com/simplyluma/luma/blob/main/src/luma-relay/luma_relay/engine.py): `src/luma-relay/luma_relay/engine.py`

### Other components

- **User**

## Connections

- User → Atlas Installer: installs through (evidence: `README.md`)
- Atlas Installer → Storage Planning: requests partitioning (evidence: `src/luma-installer-atlas/src/hooks/Storage.jsx`)
- Atlas Installer → Luma OS: installs
- Luma OS → Update Agent: receives updates
- User → Shared Applications: uses (evidence: `README.md`)
- Shared Applications → Application Kit: uses shared platform (evidence: `README.md`)
- Shared Applications → Application Portals: uses portals (evidence: `README.md`)
- User → Disks App: manages disks
- User → Charlie Mail: uses mail (evidence: `README.md`)
- User → Viola Browser: uses browser (evidence: `README.md`)
- User → Desktop Shell: interacts with (evidence: `README.md`)
- Desktop Shell → Android Compatibility: offers compatibility (evidence: `README.md`)
- Android Compatibility → Android Kernel Layer: uses kernel support (evidence: `src/luma-android/luma_android/engine.py`)
- User → Background Manager: controls background apps
- User → Energy Manager: uses power services
- User → Luma Tester: qualifies images
- User → Device Profiles: uses supported profiles (evidence: `README.md`)
- User → Continuity: uses continuity
- User → Windows App Relay: runs Windows apps
