# noctalia-dev/noctalia architecture

> Architecture diagram of the GitHub repository noctalia-dev/noctalia, 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/noctalia-dev/noctalia
- Repository: https://github.com/noctalia-dev/noctalia

## Overview

Noctalia is a native Wayland desktop shell: users interact with shell surfaces and services that provide bars, widgets, launcher, notifications, wallpaper, lock screen, and runtime controls. The README describes these capabilities and their compositor relationship; the source tree shows their implementation areas, while sampled excerpts expose selected wiring such as panel surface setup, plugin management, and notification history. The graph preserves documented product branches but omits uncertain internal call paths: much of the application and shell source was not excerpted, and some indexed core paths are absent from the supplied tree.

Main entry points: [`src/app/application.cpp`](https://github.com/noctalia-dev/noctalia/blob/main/src/app/application.cpp) (Application coordinator), [`src/shell/panel/panel_manager.cpp`](https://github.com/noctalia-dev/noctalia/blob/main/src/shell/panel/panel_manager.cpp) (Panels and launcher), [`src/notification/notification_manager.cpp`](https://github.com/noctalia-dev/noctalia/blob/main/src/notification/notification_manager.cpp) (Notification center), [`src/compositors/compositor_platform.cpp`](https://github.com/noctalia-dev/noctalia/blob/main/src/compositors/compositor_platform.cpp) (Compositor integration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Shell runtime"]
  node_entry["Application startup<br/>[main.cpp]"]
  node_app["Application coordinator<br/>[application.cpp]"]
  node_ipc["Runtime IPC<br/>[ipc_service.h]"]
end

subgraph group_surfaces["Desktop surfaces"]
  node_panel["Panels and launcher<br/>[panel_manager.cpp]"]
  node_bar["Bar and widgets<br/>[bar.cpp]"]
  node_desktop["Desktop widgets"]
  node_render["Rendering engine<br/>[render_context.cpp]"]
  node_wallpaper["Wallpaper surfaces<br/>[backdrop.cpp]"]
  node_lockscreen["Lock screen"]
end

subgraph group_services["Shell services"]
  node_notifications["Notification center"]
  node_calendar["Calendar reminders"]
  node_capture["Screenshot capture"]
  node_clipboard["Clipboard history"]
  node_dbus["System services"]
  node_idle["Idle management<br/>[idle_manager.cpp]"]
end

subgraph group_extension["Configuration and extensions"]
  node_config["Configuration service<br/>[config_service.h]"]
  node_theme["Theme templates"]
  node_plugins["Plugin manager<br/>[plugin_manager.cpp]"]
end

subgraph group_platform["Wayland platform"]
  node_compositor["Compositor integration"]
end

node_user(("Desktop user"))
node_external{{"Wayland compositor"}}

node_user -->|"starts shell"| node_entry
node_entry -->|"starts"| node_app
node_user -->|"uses surfaces"| node_panel
node_user -->|"receives alerts"| node_notifications
node_user -->|"uses history"| node_clipboard
node_user -->|"controls runtime"| node_ipc
node_app -->|"includes service"| node_calendar
node_app -->|"includes service"| node_capture
node_app -->|"includes platform"| node_compositor
node_app -->|"includes service"| node_config
node_app -->|"syncs daemon"| node_notifications
node_app -->|"updates plugins"| node_plugins
node_app -.->|"manages panels"| node_panel
node_panel -->|"sets scene"| node_render
node_panel -->|"creates surface"| node_compositor
node_external -->|"provides protocols"| node_compositor
node_external -->|"provides idle events"| node_idle
node_config -.->|"applies templates"| node_theme
node_plugins -.->|"adds panels"| node_panel
node_notifications -->|"shows toasts"| node_user
node_user -->|"selects wallpaper"| node_wallpaper
node_user -->|"locks session"| node_lockscreen
node_user -->|"uses widgets"| node_desktop
node_app -.->|"coordinates idle"| node_idle
node_app -.->|"integrates services"| node_dbus

click node_entry "https://github.com/noctalia-dev/noctalia/blob/main/src/main.cpp"
click node_app "https://github.com/noctalia-dev/noctalia/blob/main/src/app/application.cpp"
click node_panel "https://github.com/noctalia-dev/noctalia/blob/main/src/shell/panel/panel_manager.cpp"
click node_bar "https://github.com/noctalia-dev/noctalia/blob/main/src/shell/bar/bar.cpp"
click node_desktop "https://github.com/noctalia-dev/noctalia/blob/main/src/shell/desktop/desktop_widgets_controller.cpp"
click node_render "https://github.com/noctalia-dev/noctalia/blob/main/src/render/render_context.cpp"
click node_notifications "https://github.com/noctalia-dev/noctalia/blob/main/src/notification/notification_manager.cpp"
click node_calendar "https://github.com/noctalia-dev/noctalia/blob/main/src/calendar/calendar_service.cpp"
click node_capture "https://github.com/noctalia-dev/noctalia/blob/main/src/capture/screenshot_service.cpp"
click node_clipboard "https://github.com/noctalia-dev/noctalia/blob/main/src/wayland/clipboard_service.cpp"
click node_compositor "https://github.com/noctalia-dev/noctalia/blob/main/src/compositors/compositor_platform.cpp"
click node_config "https://github.com/noctalia-dev/noctalia/blob/main/src/config/config_service.h"
click node_theme "https://github.com/noctalia-dev/noctalia/blob/main/src/theme/template_engine.cpp"
click node_plugins "https://github.com/noctalia-dev/noctalia/blob/main/src/scripting/plugin_manager.cpp"
click node_ipc "https://github.com/noctalia-dev/noctalia/blob/main/src/ipc/ipc_service.h"
click node_dbus "https://github.com/noctalia-dev/noctalia/blob/main/src/dbus/network/network_manager_service.cpp"
click node_idle "https://github.com/noctalia-dev/noctalia/blob/main/src/idle/idle_manager.cpp"
click node_wallpaper "https://github.com/noctalia-dev/noctalia/blob/main/src/shell/backdrop/backdrop.cpp"
click node_lockscreen "https://github.com/noctalia-dev/noctalia/blob/main/src/shell/lockscreen/lockscreen_widgets_controller.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_entry,node_app,node_ipc,node_user toneBlue
class node_panel,node_bar,node_desktop,node_render,node_wallpaper,node_lockscreen toneAmber
class node_notifications,node_calendar,node_capture,node_clipboard,node_dbus,node_idle toneMint
class node_config,node_theme,node_plugins toneRose
class node_compositor,node_external toneIndigo
```

## Components

### Shell runtime

- [Application startup](https://github.com/noctalia-dev/noctalia/blob/main/src/main.cpp): `src/main.cpp`
- [Application coordinator](https://github.com/noctalia-dev/noctalia/blob/main/src/app/application.cpp): `src/app/application.cpp`
- [Runtime IPC](https://github.com/noctalia-dev/noctalia/blob/main/src/ipc/ipc_service.h): `src/ipc/ipc_service.h`

### Desktop surfaces

- [Panels and launcher](https://github.com/noctalia-dev/noctalia/blob/main/src/shell/panel/panel_manager.cpp): `src/shell/panel/panel_manager.cpp`
- [Bar and widgets](https://github.com/noctalia-dev/noctalia/blob/main/src/shell/bar/bar.cpp): `src/shell/bar/bar.cpp`
- [Desktop widgets](https://github.com/noctalia-dev/noctalia/blob/main/src/shell/desktop/desktop_widgets_controller.cpp): `src/shell/desktop/desktop_widgets_controller.cpp`
- [Rendering engine](https://github.com/noctalia-dev/noctalia/blob/main/src/render/render_context.cpp): `src/render/render_context.cpp`
- [Wallpaper surfaces](https://github.com/noctalia-dev/noctalia/blob/main/src/shell/backdrop/backdrop.cpp): `src/shell/backdrop/backdrop.cpp`
- [Lock screen](https://github.com/noctalia-dev/noctalia/blob/main/src/shell/lockscreen/lockscreen_widgets_controller.cpp): `src/shell/lockscreen/lockscreen_widgets_controller.cpp`

### Shell services

- [Notification center](https://github.com/noctalia-dev/noctalia/blob/main/src/notification/notification_manager.cpp): `src/notification/notification_manager.cpp`
- [Calendar reminders](https://github.com/noctalia-dev/noctalia/blob/main/src/calendar/calendar_service.cpp): `src/calendar/calendar_service.cpp`
- [Screenshot capture](https://github.com/noctalia-dev/noctalia/blob/main/src/capture/screenshot_service.cpp): `src/capture/screenshot_service.cpp`
- [Clipboard history](https://github.com/noctalia-dev/noctalia/blob/main/src/wayland/clipboard_service.cpp): `src/wayland/clipboard_service.cpp`
- [System services](https://github.com/noctalia-dev/noctalia/blob/main/src/dbus/network/network_manager_service.cpp): `src/dbus/network/network_manager_service.cpp`
- [Idle management](https://github.com/noctalia-dev/noctalia/blob/main/src/idle/idle_manager.cpp): `src/idle/idle_manager.cpp`

### Configuration and extensions

- [Configuration service](https://github.com/noctalia-dev/noctalia/blob/main/src/config/config_service.h): `src/config/config_service.h`
- [Theme templates](https://github.com/noctalia-dev/noctalia/blob/main/src/theme/template_engine.cpp): `src/theme/template_engine.cpp`
- [Plugin manager](https://github.com/noctalia-dev/noctalia/blob/main/src/scripting/plugin_manager.cpp): `src/scripting/plugin_manager.cpp`

### Wayland platform

- [Compositor integration](https://github.com/noctalia-dev/noctalia/blob/main/src/compositors/compositor_platform.cpp): `src/compositors/compositor_platform.cpp`

### Other components

- **Desktop user**
- **Wayland compositor**

## Connections

- Desktop user → Application startup: starts shell (evidence: `README.md`)
- Application startup → Application coordinator: starts (evidence: `src/main.cpp`)
- Desktop user → Panels and launcher: uses surfaces (evidence: `README.md`)
- Desktop user → Notification center: receives alerts (evidence: `README.md`)
- Desktop user → Clipboard history: uses history (evidence: `README.md`)
- Desktop user → Runtime IPC: controls runtime (evidence: `README.md`)
- Application coordinator → Calendar reminders: includes service
- Application coordinator → Screenshot capture: includes service
- Application coordinator → Compositor integration: includes platform
- Application coordinator → Configuration service: includes service
- Application coordinator → Notification center: syncs daemon
- Application coordinator → Plugin manager: updates plugins
- Application coordinator → Panels and launcher: manages panels
- Panels and launcher → Rendering engine: sets scene (evidence: `src/shell/panel/panel_manager.cpp`)
- Panels and launcher → Compositor integration: creates surface (evidence: `src/shell/panel/panel_manager.cpp`)
- Wayland compositor → Compositor integration: provides protocols (evidence: `README.md`)
- Wayland compositor → Idle management: provides idle events (evidence: `src/idle/idle_manager.cpp`)
- Configuration service → Theme templates: applies templates
- Plugin manager → Panels and launcher: adds panels
- Notification center → Desktop user: shows toasts (evidence: `README.md`)
- Desktop user → Wallpaper surfaces: selects wallpaper (evidence: `README.md`)
- Desktop user → Lock screen: locks session (evidence: `README.md`)
- Desktop user → Desktop widgets: uses widgets (evidence: `README.md`)
- Application coordinator → Idle management: coordinates idle
- Application coordinator → System services: integrates services
