# webosose/luna-surfacemanager architecture

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

- Interactive diagram: https://gitdiagram.com/webosose/luna-surfacemanager
- Repository: https://github.com/webosose/luna-surfacemanager

## Overview

Luna surface manager is the webOS Wayland compositor, implemented with Qt/QML. Its principal workflow starts the compositor, establishes its window and core, then manages client surfaces and their presentation and input. The repository also provides shell-surface handling, grouped surfaces, foreign surface export/import, input-method support, and compositor extensions. Relationships below are limited to startup calls visible in the excerpt, explicit source references, and documented behavior; several implementation files were not sampled, so some subsystem links are intentionally omitted.

Main entry points: [`base/src/main.cpp`](https://github.com/webosose/luna-surfacemanager/blob/master/base/src/main.cpp) (Compositor launcher), [`modules/weboscompositor/weboscorecompositor.cpp`](https://github.com/webosose/luna-surfacemanager/blob/master/modules/weboscompositor/weboscorecompositor.cpp) (Core compositor), [`modules/weboscompositor/foreign/webosforeign.cpp`](https://github.com/webosose/luna-surfacemanager/blob/master/modules/weboscompositor/foreign/webosforeign.cpp) (Foreign surfaces), [`modules/weboscompositor/webossurfaceitem.cpp`](https://github.com/webosose/luna-surfacemanager/blob/master/modules/weboscompositor/webossurfaceitem.cpp) (Surface items)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_startup["Startup and core"]
  node_launcher["Compositor launcher<br/>[main.cpp]"]
  node_config["Compositor config"]
  node_window["Compositor window"]
  node_core["Core compositor"]
end

subgraph group_surfaces["Surface management"]
  node_surface["Surface items"]
  node_surface_model["Surface model"]
  node_shell["Shell surfaces"]
  node_surface_groups["Surface groups"]
  node_window_model["Window models"]
end

subgraph group_integration["Platform integrations"]
  node_foreign["Foreign surfaces<br/>[webosforeign.cpp]"]
  node_video_output["Video output"]
  node_video_informer["Video informer"]
end

subgraph group_input["Input methods"]
  node_input_context["Input context"]
  node_input_method["Input method"]
  node_input_manager["IME manager"]
  node_input_panel["Input panel"]
  node_text_model["Text model"]
end

subgraph group_extensions["Compositor extensions"]
  node_extensions["Extension API"]
  node_extension_loader["Extension factory"]
end

node_actor(("webOS runtime"))
node_ime_service(("IME service"))

node_actor -->|"starts"| node_launcher
node_launcher -->|"reads config"| node_config
node_launcher -->|"creates window"| node_window
node_launcher -->|"initializes"| node_core
node_launcher -->|"loads plugin"| node_extension_loader
node_core -->|"uses config"| node_config
node_core -->|"creates items"| node_surface
node_core -->|"creates method"| node_input_method
node_core -->|"creates foreign handler"| node_foreign
node_surface -->|"uses shell state"| node_shell
node_surface_groups -->|"groups items"| node_surface
node_surface_groups -->|"updates model"| node_window_model
node_surface -.->|"backs model"| node_surface_model
node_foreign -->|"exports surfaces"| node_surface
node_foreign -->|"checks geometry"| node_window
node_foreign -->|"uses communicator"| node_video_output
node_foreign -->|"uses informer"| node_video_informer
node_input_context -->|"notifies context"| node_input_method
node_input_context -->|"requests service"| node_input_manager
node_input_context -->|"updates model"| node_text_model
node_input_context -->|"updates panel"| node_input_panel
node_input_manager -->|"activates service"| node_ime_service
node_extension_loader -.->|"loads extension"| node_extensions

click node_launcher "https://github.com/webosose/luna-surfacemanager/blob/master/base/src/main.cpp"
click node_config "https://github.com/webosose/luna-surfacemanager/blob/master/modules/weboscompositor/weboscompositorconfig.cpp"
click node_window "https://github.com/webosose/luna-surfacemanager/blob/master/modules/weboscompositor/weboscompositorwindow.cpp"
click node_core "https://github.com/webosose/luna-surfacemanager/blob/master/modules/weboscompositor/weboscorecompositor.cpp"
click node_surface "https://github.com/webosose/luna-surfacemanager/blob/master/modules/weboscompositor/webossurfaceitem.cpp"
click node_surface_model "https://github.com/webosose/luna-surfacemanager/blob/master/modules/weboscompositor/webossurfacemodel.cpp"
click node_shell "https://github.com/webosose/luna-surfacemanager/blob/master/modules/weboscompositor/shell/webosshellsurface.cpp"
click node_surface_groups "https://github.com/webosose/luna-surfacemanager/blob/master/modules/weboscompositor/surfacegroup/webossurfacegroup.cpp"
click node_window_model "https://github.com/webosose/luna-surfacemanager/blob/master/modules/weboscompositor/weboswindowmodel.cpp"
click node_foreign "https://github.com/webosose/luna-surfacemanager/blob/master/modules/weboscompositor/foreign/webosforeign.cpp"
click node_video_output "https://github.com/webosose/luna-surfacemanager/blob/master/modules/weboscompositor/foreign/videooutputd_communicator.cpp"
click node_video_informer "https://github.com/webosose/luna-surfacemanager/blob/master/modules/weboscompositor/foreign/videowindow_informer.cpp"
click node_input_context "https://github.com/webosose/luna-surfacemanager/blob/master/modules/weboscompositor/input/waylandinputmethodcontext.cpp"
click node_input_method "https://github.com/webosose/luna-surfacemanager/blob/master/modules/weboscompositor/input/waylandinputmethod.cpp"
click node_input_manager "https://github.com/webosose/luna-surfacemanager/blob/master/modules/weboscompositor/input/waylandinputmethodmanager.cpp"
click node_input_panel "https://github.com/webosose/luna-surfacemanager/blob/master/modules/weboscompositor/input/waylandinputpanel.cpp"
click node_text_model "https://github.com/webosose/luna-surfacemanager/blob/master/modules/weboscompositor/input/waylandtextmodel.cpp"
click node_extensions "https://github.com/webosose/luna-surfacemanager/blob/master/modules/weboscompositorextension/compositorextension.cpp"
click node_extension_loader "https://github.com/webosose/luna-surfacemanager/blob/master/modules/weboscompositor/compositorextensionfactory.cpp"

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_launcher,node_config,node_window,node_core toneBlue
class node_surface,node_surface_model,node_shell,node_surface_groups,node_window_model toneAmber
class node_foreign,node_video_output,node_video_informer toneMint
class node_input_context,node_input_method,node_input_manager,node_input_panel,node_text_model toneRose
class node_extensions,node_extension_loader,node_actor,node_ime_service toneIndigo
```

## Components

### Startup and core

- [Compositor launcher](https://github.com/webosose/luna-surfacemanager/blob/master/base/src/main.cpp): `base/src/main.cpp`
- [Compositor config](https://github.com/webosose/luna-surfacemanager/blob/master/modules/weboscompositor/weboscompositorconfig.cpp): `modules/weboscompositor/weboscompositorconfig.cpp`
- [Compositor window](https://github.com/webosose/luna-surfacemanager/blob/master/modules/weboscompositor/weboscompositorwindow.cpp): `modules/weboscompositor/weboscompositorwindow.cpp`
- [Core compositor](https://github.com/webosose/luna-surfacemanager/blob/master/modules/weboscompositor/weboscorecompositor.cpp): `modules/weboscompositor/weboscorecompositor.cpp`

### Surface management

- [Surface items](https://github.com/webosose/luna-surfacemanager/blob/master/modules/weboscompositor/webossurfaceitem.cpp): `modules/weboscompositor/webossurfaceitem.cpp`
- [Surface model](https://github.com/webosose/luna-surfacemanager/blob/master/modules/weboscompositor/webossurfacemodel.cpp): `modules/weboscompositor/webossurfacemodel.cpp`
- [Shell surfaces](https://github.com/webosose/luna-surfacemanager/blob/master/modules/weboscompositor/shell/webosshellsurface.cpp): `modules/weboscompositor/shell/webosshellsurface.cpp`
- [Surface groups](https://github.com/webosose/luna-surfacemanager/blob/master/modules/weboscompositor/surfacegroup/webossurfacegroup.cpp): `modules/weboscompositor/surfacegroup/webossurfacegroup.cpp`
- [Window models](https://github.com/webosose/luna-surfacemanager/blob/master/modules/weboscompositor/weboswindowmodel.cpp): `modules/weboscompositor/weboswindowmodel.cpp`

### Platform integrations

- [Foreign surfaces](https://github.com/webosose/luna-surfacemanager/blob/master/modules/weboscompositor/foreign/webosforeign.cpp): `modules/weboscompositor/foreign/webosforeign.cpp`
- [Video output](https://github.com/webosose/luna-surfacemanager/blob/master/modules/weboscompositor/foreign/videooutputd_communicator.cpp): `modules/weboscompositor/foreign/videooutputd_communicator.cpp`
- [Video informer](https://github.com/webosose/luna-surfacemanager/blob/master/modules/weboscompositor/foreign/videowindow_informer.cpp): `modules/weboscompositor/foreign/videowindow_informer.cpp`

### Input methods

- [Input context](https://github.com/webosose/luna-surfacemanager/blob/master/modules/weboscompositor/input/waylandinputmethodcontext.cpp): `modules/weboscompositor/input/waylandinputmethodcontext.cpp`
- [Input method](https://github.com/webosose/luna-surfacemanager/blob/master/modules/weboscompositor/input/waylandinputmethod.cpp): `modules/weboscompositor/input/waylandinputmethod.cpp`
- [IME manager](https://github.com/webosose/luna-surfacemanager/blob/master/modules/weboscompositor/input/waylandinputmethodmanager.cpp): `modules/weboscompositor/input/waylandinputmethodmanager.cpp`
- [Input panel](https://github.com/webosose/luna-surfacemanager/blob/master/modules/weboscompositor/input/waylandinputpanel.cpp): `modules/weboscompositor/input/waylandinputpanel.cpp`
- [Text model](https://github.com/webosose/luna-surfacemanager/blob/master/modules/weboscompositor/input/waylandtextmodel.cpp): `modules/weboscompositor/input/waylandtextmodel.cpp`

### Compositor extensions

- [Extension API](https://github.com/webosose/luna-surfacemanager/blob/master/modules/weboscompositorextension/compositorextension.cpp): `modules/weboscompositorextension/compositorextension.cpp`
- [Extension factory](https://github.com/webosose/luna-surfacemanager/blob/master/modules/weboscompositor/compositorextensionfactory.cpp): `modules/weboscompositor/compositorextensionfactory.cpp`

### Other components

- **webOS runtime**
- **IME service**

## Connections

- webOS runtime → Compositor launcher: starts (evidence: `base/src/main.cpp`)
- Compositor launcher → Compositor config: reads config (evidence: `base/src/main.cpp`)
- Compositor launcher → Compositor window: creates window (evidence: `base/src/main.cpp`)
- Compositor launcher → Core compositor: initializes (evidence: `base/src/main.cpp`)
- Compositor launcher → Extension factory: loads plugin (evidence: `base/src/main.cpp`)
- Core compositor → Compositor config: uses config
- Core compositor → Surface items: creates items
- Core compositor → Input method: creates method
- Core compositor → Foreign surfaces: creates foreign handler
- Surface items → Shell surfaces: uses shell state
- Surface groups → Surface items: groups items (evidence: `modules/weboscompositor/surfacegroup/webossurfacegroup.cpp`)
- Surface groups → Window models: updates model (evidence: `modules/weboscompositor/surfacegroup/webossurfacegroup.cpp`)
- Surface items → Surface model: backs model
- Foreign surfaces → Surface items: exports surfaces (evidence: `modules/weboscompositor/foreign/webosforeign.cpp`)
- Foreign surfaces → Compositor window: checks geometry (evidence: `modules/weboscompositor/foreign/webosforeign.cpp`)
- Foreign surfaces → Video output: uses communicator (evidence: `modules/weboscompositor/foreign/webosforeign.cpp`)
- Foreign surfaces → Video informer: uses informer (evidence: `modules/weboscompositor/foreign/webosforeign.cpp`)
- Input context → Input method: notifies context (evidence: `modules/weboscompositor/input/waylandinputmethodcontext.cpp`)
- Input context → IME manager: requests service (evidence: `modules/weboscompositor/input/waylandinputmethodcontext.cpp`)
- Input context → Text model: updates model (evidence: `modules/weboscompositor/input/waylandinputmethodcontext.cpp`)
- Input context → Input panel: updates panel (evidence: `modules/weboscompositor/input/waylandinputmethodcontext.cpp`)
- IME manager → IME service: activates service (evidence: `modules/weboscompositor/input/waylandinputmethodmanager.cpp`)
- Extension factory → Extension API: loads extension
