# aylur/astal architecture

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

- Interactive diagram: https://gitdiagram.com/aylur/astal
- Repository: https://github.com/aylur/astal

## Overview

##### Project type and purpose
- Astal is a modular monorepo of Vala/C libraries that provide the backend foundation for lightweight widgets and desktop shells.
- It exposes core services (input/output, event loops, widget containers) and higher-level feature libraries (battery, network, auth, Bluetooth, etc.), plus language bindings and example apps.

##### File structure
Top-level folders reveal the architecture layers:
- lib/ – dozens of Meson subprojects each shipping a library (astal core, gtk3/gtk4 widgets, IO, auth, powerprofiles, network, etc.)
- lang/ – language-binding subprojects (GJS/TypeScript, Lua) that wrap the C/Vala APIs via GIR
- examples/ – real-world sample apps against various stacks (GTK3, GTK4) in multiple languages
- docs/ – a VitePress-driven documentation site
- build/config files – Meson.build, default.nix/flake.nix, GitHub workflows

##### README for additional insights
- Confirms “collection of libraries written in Vala and C”

##### Components & relationships
a. Main components:
- Core library layer (“lib/astal”) – provides application lifecycle, configuration, process/time abstractions
- Backend logic libraries – e.g., io, auth, battery, bluetooth, network, notifd, tray, powerprofiles, river, wireplumber, greet, cava
- Widget layers – gtk3 and gtk4 bindings under “lib/astal/gtk3” and “lib/astal/gtk4”
- Application layer (“lib/apps”) – command-line tools and demos using the libraries
- Language bindings (“lang/gjs”, “lang/lua”) – expose the same APIs to JS/TS and Lua consumers
- Example apps (“examples/…”) – concrete GTK3/GTK4 sample bars in Python, Vala, JS/TS
- Documentation site (“docs/”)
- Build & packaging – Meson build files, Nix flake, GitHub Actions workflows

b. Relationships & interactions:
- Applications and examples import widget libraries (gtk3/gtk4) and feature libs (battery, auth, etc.)
- Widget libraries depend on the core Astal library and on GNOME/GTK GIR metadata
- Language bindings consume GIR metadata generated from the Vala/C libraries
- Meson.build orchestrates compilation, GIR generation, VAPI exports, and builds each subproject
- Nix/flake provides reproducible packaging and development shells
- Docs site pulls API docs (via gi-docgen) and example code snippets

c. Architectural patterns & design principles:
- Modular monorepo: each library is an independent Meson subproject
- Layered architecture: core → backend services → widget layer → applications
- Language-independent API surface via GIR (GNOME Introspection)
- Declarative build pipelines (Meson + Nix flakes)
- Clear separation of concerns: backends do not depend on any UI toolkit

d. Key technologies & frameworks:
- Vala and C for library implementation
- Meson build system + GIR for introspection
- Nix flakes for reproducible environments and packaging
- GTK3 and GTK4 for widget layers
- JavaScript/TypeScript (GJS) and Lua for dynamic language bindings
- VitePress for documentation

##### Detail & thoroughness
- Flow from source code → Meson build → GIR → language binding generation → final artifacts
- Documentation generation path from source comments through gi-docgen → VitePress

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Core & Service Libraries Layer
    subgraph "Core & Service Libraries"
        direction TB
        Core["Astal Core Library"]:::blue
        subgraph "Device Service Libraries"
            direction TB
            IO["IO Service"]:::blue
            Auth["Authentication Service"]:::blue
            Battery["Battery Service"]:::blue
            Bluetooth["Bluetooth Service"]:::blue
            Network["Network Service"]:::blue
            Notifd["Notification Daemon"]:::blue
            Power["Power Profiles"]:::blue
            River["River Wayland Integration"]:::blue
            Tray["Tray Service"]:::blue
            Cava["Cava Audio Visualization"]:::blue
            Hyprland["Hyprland Client"]:::blue
            Greet["Greet Service"]:::blue
            MPRIS["MPRIS Media Control"]:::blue
            Wireplumber["WirePlumber Integration"]:::blue
        end
    end

    %% Widget Layers
    subgraph "Widget Layers"
        direction TB
        GTK3["GTK3 Widget Bindings"]:::green
        GTK4["GTK4 Widget Bindings"]:::green
    end

    %% Language Bindings
    subgraph "Language Bindings"
        direction TB
        GJS["JavaScript/TypeScript (GJS)"]:::orange
        Lua["Lua Bindings"]:::orange
    end

    %% Applications & Examples
    subgraph "Applications & Example Apps"
        direction TB
        Apps["Application Layer"]:::purple
        subgraph "Example Applications"
            direction TB
            ExPy3["GTK3 Python Example"]:::purple
            ExVal3["GTK3 Vala Example"]:::purple
            ExJS4["GTK4 JavaScript Example"]:::purple
            ExPy4["GTK4 Python Example"]:::purple
            ExVal4["GTK4 Vala Example"]:::purple
        end
    end

    %% Build, Packaging & Documentation
    subgraph "Build, Packaging & Docs"
        direction TB
        Meson["Meson Build System"]:::grey
        Nix["Nix Flakes & Dev Shell"]:::grey
        CI["GitHub Actions"]:::grey
        Docs["Documentation Site"]:::grey
    end

    %% Dependencies & Relationships
    IO -->|depends on| Core
    Auth -->|depends on| Core
    Battery -->|depends on| Core
    Bluetooth -->|depends on| Core
    Network -->|depends on| Core
    Notifd -->|depends on| Core
    Power -->|depends on| Core
    River -->|depends on| Core
    Tray -->|depends on| Core
    Cava -->|depends on| Core
    Hyprland -->|depends on| Core
    Greet -->|depends on| Core
    MPRIS -->|depends on| Core
    Wireplumber -->|depends on| Core

    GTK3 -->|links to| Core
    GTK3 -->|links to| IO
    GTK4 -->|links to| Core
    GTK4 -->|links to| IO

    GJS -->|imports GIR metadata from| Core
    GJS -->|imports GIR metadata from| IO
    Lua -->|imports GIR metadata from| Core
    Lua -->|imports GIR metadata from| IO

    Apps -->|uses| GTK3
    Apps -->|uses| GTK4
    Apps -->|uses| Battery
    Apps -->|uses| Network

    ExPy3 -->|built on| GTK3
    ExVal3 -->|built on| GTK3
    ExJS4 -->|built on| GTK4
    ExPy4 -->|built on| GTK4
    ExVal4 -->|built on| GTK4

    Meson -->|builds| Core
    Meson -->|builds| IO
    Meson -->|generates GIR| Core
    Meson -->|generates GIR| IO
    Nix -->|provides| Meson
    CI -->|runs| Meson
    Docs -->|pulls API docs via gi-docgen| Core
    Docs -->|includes examples| ExPy3

    %% Click Events
    click Core "https://github.com/aylur/astal/tree/main/lib/astal"
    click Meson "https://github.com/aylur/astal/blob/main/lib/astal/meson.build"
    click IO "https://github.com/aylur/astal/tree/main/lib/astal/io"
    click Auth "https://github.com/aylur/astal/tree/main/lib/auth"
    click Battery "https://github.com/aylur/astal/tree/main/lib/battery"
    click Bluetooth "https://github.com/aylur/astal/tree/main/lib/bluetooth"
    click Network "https://github.com/aylur/astal/tree/main/lib/network"
    click Notifd "https://github.com/aylur/astal/tree/main/lib/notifd"
    click Power "https://github.com/aylur/astal/tree/main/lib/powerprofiles"
    click River "https://github.com/aylur/astal/tree/main/lib/river"
    click Tray "https://github.com/aylur/astal/tree/main/lib/tray"
    click Cava "https://github.com/aylur/astal/tree/main/lib/cava"
    click Hyprland "https://github.com/aylur/astal/tree/main/lib/hyprland"
    click Greet "https://github.com/aylur/astal/tree/main/lib/greet"
    click MPRIS "https://github.com/aylur/astal/tree/main/lib/mpris"
    click Wireplumber "https://github.com/aylur/astal/tree/main/lib/wireplumber"
    click GTK3 "https://github.com/aylur/astal/tree/main/lib/astal/gtk3"
    click GTK4 "https://github.com/aylur/astal/tree/main/lib/astal/gtk4"
    click Apps "https://github.com/aylur/astal/tree/main/lib/apps"
    click GJS "https://github.com/aylur/astal/tree/main/lang/gjs"
    click Lua "https://github.com/aylur/astal/tree/main/lang/lua"
    click ExPy3 "https://github.com/aylur/astal/tree/main/examples/gtk3/py/simple-bar"
    click ExVal3 "https://github.com/aylur/astal/tree/main/examples/gtk3/vala/simple-bar"
    click ExJS4 "https://github.com/aylur/astal/tree/main/examples/gtk4/simple-bar/js"
    click ExPy4 "https://github.com/aylur/astal/tree/main/examples/gtk4/simple-bar/py"
    click ExVal4 "https://github.com/aylur/astal/tree/main/examples/gtk4/simple-bar/vala"
    click Docs "https://github.com/aylur/astal/tree/main/docs/"
    click Nix "https://github.com/aylur/astal/blob/main/nix/devshell.nix"
    click CI "https://github.com/aylur/astal/blob/main/.github/workflows/gi-docs.yml"

    %% Styles
    classDef blue fill:#D0E8FF,stroke:#005B96,stroke-width:1px
    classDef green fill:#DFFFD0,stroke:#4CAF50,stroke-width:1px
    classDef orange fill:#FFEFD0,stroke:#FF9800,stroke-width:1px
    classDef purple fill:#F0D0FF,stroke:#9C27B0,stroke-width:1px
    classDef grey fill:#E0E0E0,stroke:#424242,stroke-width:1px
```
