# zeus-deus/gazelle-tui architecture

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

- Interactive diagram: https://gitdiagram.com/zeus-deus/gazelle-tui
- Repository: https://github.com/zeus-deus/gazelle-tui

## Overview

##### Project type and purpose
- Gazelle is a single-binary, terminal-based TUI (Text User Interface) client for NetworkManager on Linux, written in Python and driven by the Textual/Rich libraries. Its purpose is to let users scan for, connect to, and manage WiFi (including full 802.1X enterprise and VPN) entirely from the terminal.

##### File structure
- Top-level files:
- app.py – entry-point, glues together TUI and network logic
- network.py – encapsulates all interactions with NetworkManager (via nmcli or D-Bus)
- gazelle – executable wrapper/script that likely points to app.py
- requirements.txt – Python dependencies (textual, rich, platformdirs, etc.)
- README.md, LICENSE, .gitignore, PKGBUILD – project metadata and packaging
- screenshots/ – sample UI images
- No separate “frontend”/“backend” directories: this is a monolith library plus an executable script.

##### Extract architectural insights from the README
- The TUI is built on Textual, driving a four-panel layout (Device, Station, Known, New).
- All stateful operations delegate to nmcli/D-Bus calls through network.py.
- User configuration persists under ~/.config/gazelle/config.json.
- External dependencies: NetworkManager daemon, nmcli tool, Linux system network stack.

##### Main components
a. Gazelle TUI Application
- Controller Layer – translates UI events into actions
- Network Abstraction (network.py) – wrapper around nmcli/D-Bus calls
- Persistence Layer – writes/reads ~/.config/gazelle/config.json via platformdirs
b. External Systems
- NetworkManager daemon (over D-Bus or CLI)
- nmcli CLI tool (invoked by network.py)
- Linux kernel networking stack
- User’s terminal emulator
c. Configuration Stores
- /etc/NetworkManager/ (system connections)
- ~/.config/gazelle/config.json (theme, saved credentials metadata)

##### Relationships and data flows
- User keystroke → Textual UI → Controller → Network Abstraction →
- If scan/connect: spawn nmcli commands or call D-Bus → NetworkManager → kernel NICs
- If theme change: write to config.json → read back on startup
- network.py processes nmcli stdout, returns data structures to Controller.

##### Architectural patterns and principles
- MVC-like separation:
- View = Textual widgets
- Controller = app.py event handlers
- Model/Service = network.py + config persistence
- Single process, event-driven architecture (async under the hood in Textual)
- Dependency inversion: UI does not call nmcli directly; it uses a network module.

##### Relevant technologies and libraries
- Python 3.8+
- Textual (TUI framework)
- Rich (styled console output)
- platformdirs (config file paths)
- NetworkManager (nmcli or D-Bus API)
- Systemd-managed NetworkManager daemon

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "User Environment"
        Term["Terminal Emulator"]:::external
    end

    subgraph "Gazelle TUI Application"
        Wrapper["Wrapper Script"]:::app
        UI["UI Layer\n(Textual Widgets)"]:::ui
        Controller["Controller Layer\n(Event Handlers)"]:::logic
        NetworkModule["Network Module\n(network.py)"]:::logic
        Persistence["Persistence Layer\n(config.json)"]:::config
    end

    subgraph "Configuration Stores"
        SysNM["/etc/NetworkManager"]:::config
        UserConfig["~/.config/gazelle/config.json"]:::config
    end

    subgraph "External Systems"
        NM["NetworkManager Daemon"]:::external
        Kernel["Linux Kernel Networking"]:::external
    end

    subgraph "Project Files"
        Req["requirements.txt"]:::docs
        Readme["README.md"]:::docs
        License["LICENSE"]:::docs
        PKGBUILD["PKGBUILD"]:::docs
        Screens["screenshots/"]:::docs
    end

    Term -->|"keystroke"| UI
    UI -->|"event"| Controller
    Controller -->|"calls"| NetworkModule
    NetworkModule -->|"nmcli scan/connect\nor D-Bus"| NM
    NM -->|"network packets"| Kernel
    NetworkModule <-->|"read/write theme"| UserConfig
    NetworkModule <-->|"read system connections"| SysNM
    UserConfig -->|"load theme"| Persistence
    Persistence -->|"apply theme"| UI
    Wrapper -->|"launch"| UI

    classDef ui fill:#CFE2F3,stroke:#000
    classDef logic fill:#D5E8D4,stroke:#000
    classDef external fill:#E4E4E4,stroke:#000
    classDef config fill:#FFF2CC,stroke:#000
    classDef docs fill:#F8CECC,stroke:#000
    classDef app fill:#D5E8D4,stroke:#000

    click UI "https://github.com/zeus-deus/gazelle-tui/blob/main/app.py"
    click Controller "https://github.com/zeus-deus/gazelle-tui/blob/main/app.py"
    click NetworkModule "https://github.com/zeus-deus/gazelle-tui/blob/main/network.py"
    click Persistence "https://github.com/zeus-deus/gazelle-tui/blob/main/app.py"
    click Wrapper "https://github.com/zeus-deus/gazelle-tui/tree/main/gazelle"
    click Req "https://github.com/zeus-deus/gazelle-tui/blob/main/requirements.txt"
    click Readme "https://github.com/zeus-deus/gazelle-tui/blob/main/README.md"
    click License "https://github.com/zeus-deus/gazelle-tui/tree/main/LICENSE"
    click PKGBUILD "https://github.com/zeus-deus/gazelle-tui/tree/main/PKGBUILD"
    click Screens "https://github.com/zeus-deus/gazelle-tui/tree/main/screenshots/"
```
