# krishnarajan7/liova architecture

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

- Interactive diagram: https://gitdiagram.com/krishnarajan7/liova
- Repository: https://github.com/krishnarajan7/liova

## Overview

Liova is a macOS menu-bar app that turns the Mac’s notch into an interactive display for system events, media, and coding-agent activity. The main path is menu-bar launch into app coordination, feature state and activity prioritization, then notch presentation; scripts and local links can also submit activities through the plugin interface. The README documents the broader feature set and opt-in network services. Several feature implementations were not sampled, so those branches use exact enclosing directories and documented relationships; edges reflect only shown imports/calls or README statements.

Main entry points: [`App/AppCoordinator.swift`](https://github.com/krishnarajan7/liova/blob/main/App/AppCoordinator.swift) (App coordinator), [`Packages/LiovaKit/Sources/LiovaUI/ActivityRenderer.swift`](https://github.com/krishnarajan7/liova/blob/main/Packages/LiovaKit/Sources/LiovaUI/ActivityRenderer.swift) (Notch rendering), [`Packages/LiovaKit/Sources/LiovaCore/ActivityEngine.swift`](https://github.com/krishnarajan7/liova/blob/main/Packages/LiovaKit/Sources/LiovaCore/ActivityEngine.swift) (Activity engine), [`Packages/LiovaKit/Sources/LiovaUI/NotchController.swift`](https://github.com/krishnarajan7/liova/blob/main/Packages/LiovaKit/Sources/LiovaUI/NotchController.swift) (Notch controller)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App and display"]
  node_menu["Menu bar<br/>[MenuBarIcon.swift]"]
  node_coordinator["App coordinator"]
  node_settings[("Settings")]
  node_display["Display manager"]
  node_notch["Notch controller"]
  node_render["Notch rendering"]
end

subgraph group_core["Core and plugin API"]
  node_engine["Activity engine"]
  node_plugin["Plugin API<br/>[Activity.swift]"]
  node_ipc["Local IPC<br/>[IPCClient.swift]"]
  node_cli["CLI commands<br/>[CLIParser.swift]"]
end

subgraph group_features["Notch features"]
  node_music["Now playing"]
  node_agent["Agent Island"]
  node_battery["Battery and headphones"]
  node_downloads["Downloads"]
  node_utilities["Notch utilities"]
  node_hud["Volume and brightness HUD<br/>[HUDFeature.swift]"]
end

subgraph group_providers["System providers"]
  node_lyrics["Lyrics service<br/>[LyricsClient.swift]"]
  node_weather["Weather service"]
  node_updates["Update service"]
end

node_user(("Mac user"))
node_socket["Local socket"]
node_scripts(("User scripts"))
node_lrclib["LRCLIB"]
node_openmeteo["Open-Meteo"]
node_github["GitHub releases"]

node_user -->|"opens"| node_menu
node_menu -.->|"launches"| node_coordinator
node_coordinator -->|"uses"| node_settings
node_coordinator -->|"uses"| node_display
node_coordinator -->|"uses"| node_engine
node_coordinator -->|"configures"| node_notch
node_coordinator -->|"starts"| node_music
node_coordinator -->|"starts"| node_hud
node_engine -->|"manages"| node_plugin
node_scripts -->|"submits activity"| node_cli
node_cli -->|"parses commands"| node_ipc
node_ipc -->|"connects over"| node_socket
node_socket -.->|"delivers activity"| node_engine
node_notch -->|"shows activity"| node_engine
node_notch -->|"hosts views"| node_render
node_music -.->|"looks up lyrics"| node_lyrics
node_lyrics -->|"fetches from"| node_lrclib
node_weather -->|"fetches from"| node_openmeteo
node_updates -->|"checks releases"| node_github
node_battery -->|"appears in notch"| node_render
node_agent -->|"appears in notch"| node_render
node_downloads -->|"appears in notch"| node_render
node_utilities -->|"appears in notch"| node_render
node_hud -->|"shows HUDs"| node_render

click node_menu "https://github.com/krishnarajan7/liova/blob/main/App/MenuBarIcon.swift"
click node_coordinator "https://github.com/krishnarajan7/liova/blob/main/App/AppCoordinator.swift"
click node_settings "https://github.com/krishnarajan7/liova/blob/main/Packages/LiovaKit/Sources/LiovaCore/LiovaSettings.swift"
click node_display "https://github.com/krishnarajan7/liova/blob/main/Packages/LiovaKit/Sources/LiovaCore/DisplayManager.swift"
click node_notch "https://github.com/krishnarajan7/liova/blob/main/Packages/LiovaKit/Sources/LiovaUI/NotchController.swift"
click node_engine "https://github.com/krishnarajan7/liova/blob/main/Packages/LiovaKit/Sources/LiovaCore/ActivityEngine.swift"
click node_plugin "https://github.com/krishnarajan7/liova/blob/main/Packages/LiovaKit/Sources/LiovaPluginKit/Activity.swift"
click node_ipc "https://github.com/krishnarajan7/liova/blob/main/Packages/LiovaKit/Sources/LiovaIPC/IPCClient.swift"
click node_cli "https://github.com/krishnarajan7/liova/blob/main/Packages/LiovaKit/Sources/LiovaIPC/CommandLine/CLIParser.swift"
click node_music "https://github.com/krishnarajan7/liova/blob/main/Packages/LiovaKit/Sources/LiovaFeatures/NowPlaying/NowPlayingFeature.swift"
click node_agent "https://github.com/krishnarajan7/liova/tree/main/Packages/LiovaKit/Sources/LiovaFeatures/Agents"
click node_battery "https://github.com/krishnarajan7/liova/tree/main/Packages/LiovaKit/Sources/LiovaFeatures"
click node_downloads "https://github.com/krishnarajan7/liova/tree/main/Packages/LiovaKit/Sources/LiovaFeatures/Downloads"
click node_utilities "https://github.com/krishnarajan7/liova/tree/main/Packages/LiovaKit/Sources/LiovaFeatures"
click node_hud "https://github.com/krishnarajan7/liova/blob/main/Packages/LiovaKit/Sources/LiovaFeatures/HUD/HUDFeature.swift"
click node_render "https://github.com/krishnarajan7/liova/blob/main/Packages/LiovaKit/Sources/LiovaUI/ActivityRenderer.swift"
click node_lyrics "https://github.com/krishnarajan7/liova/blob/main/Packages/LiovaKit/Sources/LiovaProviders/Lyrics/LyricsClient.swift"
click node_weather "https://github.com/krishnarajan7/liova/blob/main/Packages/LiovaKit/Sources/LiovaProviders/Weather/OpenMeteoClient.swift"
click node_updates "https://github.com/krishnarajan7/liova/blob/main/Packages/LiovaKit/Sources/LiovaProviders/Updates/GitHubReleaseClient.swift"

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_menu,node_coordinator,node_settings,node_display,node_notch,node_render,node_user,node_scripts toneBlue
class node_engine,node_plugin,node_ipc,node_cli toneAmber
class node_music,node_agent,node_battery,node_downloads,node_utilities,node_hud toneMint
class node_lyrics,node_weather,node_updates toneRose
class node_socket,node_lrclib,node_openmeteo,node_github toneIndigo
```

## Components

### App and display

- [Menu bar](https://github.com/krishnarajan7/liova/blob/main/App/MenuBarIcon.swift): `App/MenuBarIcon.swift`
- [App coordinator](https://github.com/krishnarajan7/liova/blob/main/App/AppCoordinator.swift): `App/AppCoordinator.swift`
- [Settings](https://github.com/krishnarajan7/liova/blob/main/Packages/LiovaKit/Sources/LiovaCore/LiovaSettings.swift): `Packages/LiovaKit/Sources/LiovaCore/LiovaSettings.swift`
- [Display manager](https://github.com/krishnarajan7/liova/blob/main/Packages/LiovaKit/Sources/LiovaCore/DisplayManager.swift): `Packages/LiovaKit/Sources/LiovaCore/DisplayManager.swift`
- [Notch controller](https://github.com/krishnarajan7/liova/blob/main/Packages/LiovaKit/Sources/LiovaUI/NotchController.swift): `Packages/LiovaKit/Sources/LiovaUI/NotchController.swift`
- [Notch rendering](https://github.com/krishnarajan7/liova/blob/main/Packages/LiovaKit/Sources/LiovaUI/ActivityRenderer.swift): `Packages/LiovaKit/Sources/LiovaUI/ActivityRenderer.swift`

### Core and plugin API

- [Activity engine](https://github.com/krishnarajan7/liova/blob/main/Packages/LiovaKit/Sources/LiovaCore/ActivityEngine.swift): `Packages/LiovaKit/Sources/LiovaCore/ActivityEngine.swift`
- [Plugin API](https://github.com/krishnarajan7/liova/blob/main/Packages/LiovaKit/Sources/LiovaPluginKit/Activity.swift): `Packages/LiovaKit/Sources/LiovaPluginKit/Activity.swift`
- [Local IPC](https://github.com/krishnarajan7/liova/blob/main/Packages/LiovaKit/Sources/LiovaIPC/IPCClient.swift): `Packages/LiovaKit/Sources/LiovaIPC/IPCClient.swift`
- [CLI commands](https://github.com/krishnarajan7/liova/blob/main/Packages/LiovaKit/Sources/LiovaIPC/CommandLine/CLIParser.swift): `Packages/LiovaKit/Sources/LiovaIPC/CommandLine/CLIParser.swift`

### Notch features

- [Now playing](https://github.com/krishnarajan7/liova/blob/main/Packages/LiovaKit/Sources/LiovaFeatures/NowPlaying/NowPlayingFeature.swift): `Packages/LiovaKit/Sources/LiovaFeatures/NowPlaying/NowPlayingFeature.swift`
- [Agent Island](https://github.com/krishnarajan7/liova/tree/main/Packages/LiovaKit/Sources/LiovaFeatures/Agents): `Packages/LiovaKit/Sources/LiovaFeatures/Agents`
- [Battery and headphones](https://github.com/krishnarajan7/liova/tree/main/Packages/LiovaKit/Sources/LiovaFeatures): `Packages/LiovaKit/Sources/LiovaFeatures`
- [Downloads](https://github.com/krishnarajan7/liova/tree/main/Packages/LiovaKit/Sources/LiovaFeatures/Downloads): `Packages/LiovaKit/Sources/LiovaFeatures/Downloads`
- [Notch utilities](https://github.com/krishnarajan7/liova/tree/main/Packages/LiovaKit/Sources/LiovaFeatures): `Packages/LiovaKit/Sources/LiovaFeatures`
- [Volume and brightness HUD](https://github.com/krishnarajan7/liova/blob/main/Packages/LiovaKit/Sources/LiovaFeatures/HUD/HUDFeature.swift): `Packages/LiovaKit/Sources/LiovaFeatures/HUD/HUDFeature.swift`

### System providers

- [Lyrics service](https://github.com/krishnarajan7/liova/blob/main/Packages/LiovaKit/Sources/LiovaProviders/Lyrics/LyricsClient.swift): `Packages/LiovaKit/Sources/LiovaProviders/Lyrics/LyricsClient.swift`
- [Weather service](https://github.com/krishnarajan7/liova/blob/main/Packages/LiovaKit/Sources/LiovaProviders/Weather/OpenMeteoClient.swift): `Packages/LiovaKit/Sources/LiovaProviders/Weather/OpenMeteoClient.swift`
- [Update service](https://github.com/krishnarajan7/liova/blob/main/Packages/LiovaKit/Sources/LiovaProviders/Updates/GitHubReleaseClient.swift): `Packages/LiovaKit/Sources/LiovaProviders/Updates/GitHubReleaseClient.swift`

### Other components

- **Mac user**
- **Local socket**
- **User scripts**
- **LRCLIB**
- **Open-Meteo**
- **GitHub releases**

## Connections

- Mac user → Menu bar: opens
- Menu bar → App coordinator: launches
- App coordinator → Settings: uses (evidence: `App/AppCoordinator.swift`)
- App coordinator → Display manager: uses (evidence: `App/AppCoordinator.swift`)
- App coordinator → Activity engine: uses (evidence: `App/AppCoordinator.swift`)
- App coordinator → Notch controller: configures (evidence: `App/AppCoordinator.swift`)
- App coordinator → Now playing: starts (evidence: `App/AppCoordinator.swift`)
- App coordinator → Volume and brightness HUD: starts (evidence: `App/AppCoordinator.swift`)
- Activity engine → Plugin API: manages (evidence: `Packages/LiovaKit/Sources/LiovaCore/ActivityEngine.swift`)
- User scripts → CLI commands: submits activity
- CLI commands → Local IPC: parses commands (evidence: `Packages/LiovaKit/Sources/LiovaIPC/CommandLine/CLIParser.swift`)
- Local IPC → Local socket: connects over
- Local socket → Activity engine: delivers activity
- Notch controller → Activity engine: shows activity (evidence: `Packages/LiovaKit/Sources/LiovaUI/NotchController.swift`)
- Notch controller → Notch rendering: hosts views (evidence: `Packages/LiovaKit/Sources/LiovaUI/NotchController.swift`)
- Now playing → Lyrics service: looks up lyrics
- Lyrics service → LRCLIB: fetches from
- Weather service → Open-Meteo: fetches from
- Update service → GitHub releases: checks releases (evidence: `Packages/LiovaKit/Sources/LiovaProviders/Updates/GitHubReleaseClient.swift`)
- Battery and headphones → Notch rendering: appears in notch
- Agent Island → Notch rendering: appears in notch
- Downloads → Notch rendering: appears in notch
- Notch utilities → Notch rendering: appears in notch
- Volume and brightness HUD → Notch rendering: shows HUDs
