How zeus-deus/gazelle-tui works
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