# matthiasgrandl/loungy architecture

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

- Interactive diagram: https://gitdiagram.com/matthiasgrandl/loungy
- Repository: https://github.com/matthiasgrandl/loungy

## Overview

##### Project type and purpose
- Loungy is a desktop application-launcher (similar to Raycast/Alfred), written primarily in Rust using GPUI for a GPU-accelerated UI, with a small Swift library for macOS native integrations. It’s a “full-stack” local app (UI + core logic + native OS bridge), not a web app or microservice.

##### File structure
- Top-level:
- src/               ← Rust application code
- swift-lib/         ← Swift package (macOS bridge)
- macos/             ← macOS entitlements & packaging
- build.rs, Cargo.toml, flake.nix ← build/config scripts
- src/ directory:
- main.rs + app.rs    ← entrypoint and application initialization
- commands/           ← pluggable features (bitwarden, clipboard, matrix, etc.) behind cargo features
- state.rs, db.rs     ← in-memory state, simple persistence
- ipc/                ← Rust-side IPC client/server to communicate with Swift
- platform/           ← OS abstractions (macOS, Linux implementations)
- query.rs, theme.rs, hotkey.rs, window.rs, workspace.rs, loader.rs, assets.rs, date.rs

##### README for additional insights
- Optional features toggled by cargo feature flags
- Primary target: macOS, experimental Linux support

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% UI Layer
    subgraph "User Interface (GPUI)"
        UI_Main["main.rs"]:::rust
        UI_App["app.rs"]:::rust
        UI_Components["src/components/"]:::rust
        UI_Loader["src/loader.rs"]:::rust
        UI_Assets["src/assets.rs"]:::rust
    end

    %% Application Core
    subgraph "Application Core"
        CP["Command Processor\n(src/commands/)"]:::rust
        SP["State & Persistence\nstate.rs, db.rs"]:::rust
        TL["Theme & Assets Loader\ntheme.rs, loader.rs, assets.rs"]:::rust
        HK["Hotkey Manager\nhotkey.rs"]:::rust
        QD["Query Dispatcher\nquery.rs"]:::rust
        WM["Window & Workspace Manager\nwindow.rs, workspace.rs"]:::rust
    end

    %% Platform Abstraction
    subgraph "Platform Abstraction Layer"
        PA["Platform Adapter\nsrc/platform/"]:::rust
        MPA["mac.rs"]:::rust
        LPA["linux/ (experimental)"]:::rust
    end

    %% IPC Layer
    subgraph "IPC Layer"
        IPCC["client.rs"]:::rust
        IPCM["mod.rs"]:::rust
        IPCS["server.rs"]:::rust
    end

    %% Native Bridge
    subgraph "Native Bridge" 
        SB["swift-lib/"]:::swift
        EP["entitlements.plist"]:::swift
    end

    %% External Services
    subgraph "External Services"
        BW["Bitwarden API"]:::external
        TS["Tailscale CLI"]:::external
        MX["Matrix API"]:::external
        OS["OS Services\n(clipboard, process mgr)"]:::external
    end

    %% Build & CI
    subgraph "Build & CI"
        BLD["build.rs\nflake.nix"]:::ci
        CICD[".github/workflows/release-macos.yml"]:::ci
    end

    %% Connections
    HK -->|"hotkey press"| UI_Main
    UI_Main -->|"init UI"| QD
    QD -->|"dispatch query"| CP
    CP -->|"read/write"| SP
    CP -->|"load theme/assets"| TL
    TL -->|"provide assets"| UI_Assets
    CP -->|"manage windows"| WM
    WM --> UI_Main
    CP -->|"platform calls"| PA
    PA --> MPA
    PA --> LPA
    PA --> IPCC
    IPCC --> IPCM
    IPCM --> IPCS
    IPCS --> SB
    SB -->|"native macOS API"| EP

    CP --> BW
    CP --> TS
    CP --> MX
    BW --> CP
    TS --> CP
    MX --> CP

    %% Build & CI context
    BLD -.-> CICD

    %% Click Events
    click UI_Main "https://github.com/matthiasgrandl/loungy/blob/main/src/main.rs"
    click UI_App "https://github.com/matthiasgrandl/loungy/blob/main/src/app.rs"
    click UI_Components "https://github.com/matthiasgrandl/loungy/tree/main/src/components/"
    click UI_Loader "https://github.com/matthiasgrandl/loungy/blob/main/src/loader.rs"
    click UI_Assets "https://github.com/matthiasgrandl/loungy/blob/main/src/assets.rs"
    click CP "https://github.com/matthiasgrandl/loungy/tree/main/src/commands/"
    click SP "https://github.com/matthiasgrandl/loungy/blob/main/src/state.rs"
    click SP "https://github.com/matthiasgrandl/loungy/blob/main/src/db.rs"
    click TL "https://github.com/matthiasgrandl/loungy/blob/main/src/theme.rs"
    click TL "https://github.com/matthiasgrandl/loungy/blob/main/src/loader.rs"
    click TL "https://github.com/matthiasgrandl/loungy/blob/main/src/assets.rs"
    click HK "https://github.com/matthiasgrandl/loungy/blob/main/src/hotkey.rs"
    click QD "https://github.com/matthiasgrandl/loungy/blob/main/src/query.rs"
    click WM "https://github.com/matthiasgrandl/loungy/blob/main/src/window.rs"
    click WM "https://github.com/matthiasgrandl/loungy/blob/main/src/workspace.rs"
    click PA "https://github.com/matthiasgrandl/loungy/tree/main/src/platform/"
    click MPA "https://github.com/matthiasgrandl/loungy/blob/main/src/platform/mac.rs"
    click LPA "https://github.com/matthiasgrandl/loungy/tree/main/src/platform/linux/"
    click IPCC "https://github.com/matthiasgrandl/loungy/blob/main/src/ipc/client.rs"
    click IPCM "https://github.com/matthiasgrandl/loungy/blob/main/src/ipc/mod.rs"
    click IPCS "https://github.com/matthiasgrandl/loungy/blob/main/src/ipc/server.rs"
    click SB "https://github.com/matthiasgrandl/loungy/tree/main/swift-lib/"
    click EP "https://github.com/matthiasgrandl/loungy/blob/main/macos/entitlements.plist"
    click BW "https://github.com/matthiasgrandl/loungy/tree/main/src/commands/bitwarden/"
    click TS "https://github.com/matthiasgrandl/loungy/tree/main/src/commands/tailscale/"
    click MX "https://github.com/matthiasgrandl/loungy/tree/main/src/commands/matrix/"
    click BLD "https://github.com/matthiasgrandl/loungy/blob/main/build.rs"
    click BLD "https://github.com/matthiasgrandl/loungy/blob/main/flake.nix"
    click CICD "https://github.com/matthiasgrandl/loungy/blob/main/.github/workflows/release-macos.yml"

    %% Styles
    classDef rust fill:#D0E8FF,stroke:#0366d6,stroke-width:1px
    classDef swift fill:#DFF5E1,stroke:#2C9F13,stroke-width:1px
    classDef external fill:#FFE4B3,stroke:#D97706,stroke-width:1px
    classDef ci fill:#EDEEF0,stroke:#6E7781,stroke-width:1px
    classDef dashed stroke-dasharray: 5 5
```
