SERVICES

Services Catalog

70+ QML singletons that handle everything that isn't pure UI. Each service is registered in services/qmldir and available as a singleton import everywhere.

Compositor

Service	What it does
NiriService	Niri IPC via Unix socket. Tracks workspaces, windows, outputs, keyboard layouts. Event-driven with reactive properties.
CompositorService	Detects compositor (Niri/Hyprland/GNOME), provides sorted toplevel windows and compositor-agnostic APIs.
HyprlandData	Hyprland window, workspace, monitor, and layer data via hyprctl.
HyprlandKeybinds	Parses Hyprland config for keybind cheatsheet.
HyprlandXkb	Keyboard layout tracking for Hyprland.

Audio and Media

Service	What it does
Audio	PipeWire integration. Default sink/source, volume, mute, per-app mixer. EasyEffects virtual sink detection. IPC target: audio.
MprisController	MPRIS player management. Filters real players, deduplicates YT Music instances, tracks active player with grace period for track transitions.
YtMusic	YouTube Music player. Search, queue, playback via mpv + yt-dlp. IPC target: ytmusic.
SongRec	Music recognition via SongRec (Shazam-like audio fingerprinting).

System

Service	What it does
Network	NetworkManager integration. WiFi networks, connection status, signal strength. IPC target: network.
BluetoothStatus	Bluetooth adapter and device status via BlueZ D-Bus.
Battery	UPower integration. Percentage, charging state, charge limit control, low/critical thresholds. IPC target: battery.
Brightness	Monitor brightness via brightnessctl (laptop) and ddcutil (external monitors). Per-screen control. IPC target: brightness.
PowerProfilePersistence	Restores the user's power profile on startup.
GameMode	Fullscreen detection with auto/manual activation. Suppresses animations, notifications, blur when gaming. IPC target: gameMode.
Idle	Idle management via swayidle. Screen-off, lock, and suspend timeouts. IPC target: idle.
ResourceUsage	CPU, RAM, GPU, temperature, disk polling. History arrays for graphs. Auto-stop timer (15s) when no consumers active. IPC target: resources.
SystemInfo	Distro name, username, desktop environment detection.
Privacy	Mic and screen sharing detection via PipeWire link analysis.

Theming and Appearance

Service	What it does
ThemeService	Theme orchestration. Applies presets, triggers wallpaper-based regeneration, manages auto vs manual mode. IPC target: theme.
MaterialThemeLoader	Watches colors.json (generated by the color pipeline) and loads Material 3 colors into Appearance tokens.
ThemePresets	44 built-in theme presets (Catppuccin, Gruvbox, Nord, Angel, etc.) with full M3 color definitions.
Wallpapers	Wallpaper management. Multi-monitor support, video wallpapers, backdrop system, auto-cycling. IPC target: wallpapers.
WallpaperListener	Multi-monitor wallpaper config resolver.
IconThemeService	Icon theme management. Syncs to GTK, KDE, Qt5ct, Qt6ct. Smart Electron app icon resolution. IPC target: iconTheme.
FontSyncService	Syncs shell fonts to GTK/KDE desktop settings.
AwwwBackend	awww animated wallpaper daemon integration.
GowallService	gowall wallpaper color extraction and palette generation. IPC target: gowall.

Data and Storage

Service	What it does
Notifications	Notification management with persistent storage, popup control, grouping, DND mode, GameMode integration. IPC target: notifications.
Cliphist	Clipboard history with fuzzy search. Uses cliphist backend. IPC target: cliphist.
Events	Local calendar events with categories, priorities, reminders, recurrence. JSON storage.
CalendarSync	External calendar sync via ICS/iCal URLs. Fetches with curl, parses in JS. Supports Google Calendar, Outlook, Nextcloud, any CalDAV.
Weather	Open-Meteo weather data with GPS, manual coordinates, or city name location. IPC target: weather.
Todo	Todo list with JSON + markdown sync.
Notepad	Persistent plaintext notepad.
KeyringStorage	Secure API key storage via GNOME Keyring (secret-tool). IPC target: keyring.
DateTime	Date/time formatting, uptime tracking.

Desktop Integration

Service	What it does
Autostart	Autostart manager. Desktop entries, custom commands, systemd units. IPC target: autostart.
TrayService	System tray with workarounds for problematic apps (Vesktop, Steam, etc.). IPC target: tray.
PolkitService	PolicyKit authentication agent for privileged operations.
Hyprsunset	Night light via wlsunset (Niri) or hyprsunset (Hyprland). Scheduled or manual. IPC target: hyprsunset.
EasyEffects	EasyEffects audio effects toggle. Supports native and flatpak. IPC target: easyeffects.
RecorderStatus	Screen recording status detection (wf-recorder).
SessionWarnings	Detects running package managers before logout.
ConflictKiller	Kills conflicting system trays and notification daemons on startup.
FirstRunExperience	First-run wizard trigger.

Application Management

Service	What it does
AppLauncher	Default app slot manager (terminal, browser, file manager, etc.). IPC target: appLauncher.
AppSearch	Desktop entry fuzzy search with icon substitution mappings.
AppCatalog	Curated software catalog with multi-distro install support. IPC target: appCatalog.
LauncherSearch	Overview search with prefix routing (apps, actions, calculator, packages).
TaskbarApps	Dock/taskbar app list (merged pinned + open windows).
MinimizedWindows	Niri window minimization via hidden workspace. IPC target: minimizedWindows.
WindowPreviewService	Window preview caching for task view.
GlobalActions	Modular action registry for keyboard-driven workflows. User-extensible. IPC target: globalActions.

Content

Service	What it does
Ai	LLM chat. Gemini, OpenAI, Mistral, OpenRouter, Ollama. Tool use, streaming, conversation history. IPC target: ai.
AnimeService	AniList GraphQL API. Anime schedule, seasonal listing. IPC target: anime.
RedditService	Reddit public JSON API. Browse subreddits inline. IPC target: reddit.
Wallhaven	Wallhaven.cc wallpaper search with rate limiting.
Booru	Multi-booru image board API (yande.re, konachan, danbooru, etc.).
VoiceSearch	Voice recording + Gemini transcription + web search. IPC target: voiceSearch.
Emojis	Emoji picker data.
PackageSearch	Async package manager search (pacman + AUR). IPC target: packageSearch.

Utilities

Service	What it does
TimerService	Pomodoro timer with persistent state. IPC target: timer.
Updates	System update checker (Arch only, uses checkupdates).
ShellUpdates	iNiR update checker. Git-based, tracks commits behind remote. IPC target: shellUpdate.
Ydotool	Virtual keyboard input for on-screen keyboard.
LatexRenderer	LaTeX math rendering via MicroTeX.
Translation	i18n string lookup. Auto language detection, 15+ languages.

For contributors

Services are stability boundaries. Changes to a service API affect every module that consumes it.

Before modifying a service:

1. Check consumer count: grep -r "ServiceName\." modules/ services/
2. Prefer add-only changes to public APIs
3. Register new services in services/qmldir
4. Add IPC targets to IPC Reference if applicable