How arekkazu/wirfi works
1. What this repo is
- wirfi is a single Rust binary that implements a terminal UI for managing WiFi on Linux.
- Its architecture is centered around one external boundary: NetworkManager over D-Bus. The app does not manage WiFi directly; it drives NetworkManager through zbus.
2. Top-level layering
- The code is split into three main layers:
- Runtime/bootstrap: main.rs, app.rs, input.rs, error.rs
- NetworkManager integration: src/nm/*
- TUI presentation: src/ui/*
- This makes the repository easy to diagram as a UI shell over a NetworkManager client layer, with a small local credential/cache layer beside it.
3. Application orchestration
- src/app.rs is the central coordinator. It likely owns the current screen/state, selected interface, current network selection, and pending operations.
- It mediates between terminal events and NetworkManager actions, so UI components stay mostly presentational.
- The app is also the place where asynchronous work is coordinated so scans and connection attempts do not block rendering.
4. Terminal input and event flow
- src/input.rs normalizes terminal key events into app actions like move, connect, disconnect, refresh, open QR, or switch screens.
- The flow is: terminal events → input handling → app state transition → UI redraw and/or NetworkManager request.
- This separation matters because the TUI is event-driven, while NM operations are async and potentially slow.
5. NetworkManager boundary
- src/nm/transport.rs is the D-Bus transport boundary for NetworkManager calls and signals.
- src/nm/types.rs defines the data models used by the app for devices, access points, connection state, and related NM concepts.
- src/nm/auth.rs and src/nm/credentials.rs handle authentication-related details such as passwords and saved connection data.
- This layer is the only part that should know NetworkManager-specific API shapes.
6. Credential and password handling
- The app uses two credential sources:
- a local cache in src/cache.rs
- NetworkManager-stored profiles via the NM layer
- The README indicates cached passwords are stored under $XDG_DATA_HOME/wirfi/cache.json with restrictive permissions, which is a separate persistence boundary from NetworkManager itself.
- This enables reconnecting and QR generation without retyping passwords, while still deferring authoritative connection storage to NM.
7. UI subsystem structure
- src/ui/ is split by screen/component rather than by business logic:
- network_list.rs: main scan-and-connect view
- details_panels.rs: right-side network/device details
- password_modal.rs: password entry overlay
- interface_select.rs: initial interface chooser
- interfaces.rs: interface browser
- qr_views.rs: QR code display
- src/ui/mod.rs ties these pieces together.
- The UI layer appears to be built with ratatui, and it renders state passed down from the app rather than fetching data itself.
8. Primary user flows
- Startup: load local cache, query NetworkManager for interfaces, and either show interface selection or go directly to scanning.
- Scan/browse: list nearby access points sorted by signal strength, with inline metadata like band and security type.
- Connect: if a password is needed, open the modal; then send credentials through NM and cache them locally if appropriate.
- Reconnect/disconnect/forget: all act on the selected saved profile or active connection via the NM layer.
- QR generation: reads stored password from cache or NM profile and renders a scannable QR view.
9. Concurrency and responsiveness
- The README says scans and connection attempts run in a background worker on tokio, which keeps the TUI responsive.
- That suggests a split between a foreground render/event loop and background NM operations, with state updates flowing back into the app model.
10. Error handling and diagnostics
- src/error.rs centralizes the app’s error type and likely normalizes failures from D-Bus, IO, parsing, and UI operations.
- Logs are written to /tmp/wirfi.log, so there is a lightweight diagnostics path outside the terminal UI.
- This is useful for drawing a separate “observability” note in the diagram, but logging is not a core subsystem.
11. External dependencies that shape the architecture
- NetworkManager is the main external service and policy boundary.
- D-Bus via zbus is the transport mechanism.
- tokio provides async execution.
- ratatui drives the terminal UI rendering model.
- These dependencies matter because they explain why the app is event-driven, asynchronous, and session-scoped rather than a privileged system daemon.
12. How to diagram the repo
- A good diagram would show:
- Terminal user input → input → app
- app → ui for rendering
- app ↔ nm layer ↔ NetworkManager over D-Bus
- app ↔ cache for local password persistence
- A background async worker feeding results back into app
- The clearest architectural boundary is between presentation/state orchestration and NetworkManager/credential backends.
Main entry points: app.rs App · ui/mod.rs UI Module · nm/mod.rs NM Module · main.rs Main
Components 21
Runtime
Startup, input normalization, and orchestration.
NetworkManager
DBus-backed NetworkManager integration and auth handling.
- Transport · NetworkManager D-Bus transport boundary.
src/nm/transport.rs - NM Types · NetworkManager-facing data models for devices, APs, and connection state.
src/nm/types.rs - Auth · NetworkManager authentication and session credential handling.
src/nm/auth.rs - Credentials · Password and saved connection data abstractions.
src/nm/credentials.rs - NM Module · Top-level NetworkManager integration module wiring subcomponents.
src/nm/mod.rs
TUI
Terminal screens and widgets.
- UI Module · Top-level TUI module wiring the screens and widgets.
src/ui/mod.rs - Network List · Main scan-and-connect view.
src/ui/network_list.rs - Details · Device and access-point detail side panels.
src/ui/details_panels.rs - Password Modal · Password entry dialog for protected networks.
src/ui/password_modal.rs - Interface Select · Initial chooser for wireless interfaces.
src/ui/interface_select.rs - Interfaces · Browser for available interfaces and their state.
src/ui/interfaces.rs - QR Views · QR code display for stored WiFi credentials.
src/ui/qr_views.rs
State
Local persistence and shared error handling.
External
Runtime dependencies and outside services.
- D-Bus · NetworkManager communication transport.
- NetworkManager · System WiFi and connection manager.
- Tokio · Background worker and async task execution.
- ratatui · Terminal rendering framework.
Connections 30
- Main → App: bootstraps · Creates the application and wires runtime components.
- Main → UI Module: starts ui · Initializes terminal presentation.
- Main → NM Module: initializes nm · Prepares NetworkManager integration.
- Input → App: dispatches · Turns terminal events into app actions.
- App → UI Module: renders via · Passes state to the TUI for drawing.
- App → Network List: drives · Main browsing and connect screen state.
- App → Details: drives · Updates detail panels from selected network or device.
- App → Password Modal: opens · Shows password prompt when credentials are needed.
- App → Interface Select: routes · Chooses the initial interface selection flow.
- App → Interfaces: routes · Browses interfaces when needed.
- App → QR Views: shows · Builds QR view from cached or stored credentials.
- App → NM Module: requests · Issues scans, connect, disconnect, forget, and profile actions.
- App → Cache: reads/writes · Loads and persists local credential cache.
- App → Errors: propagates · Normalizes failures from UI, IO, and backend calls.
- NM Module → Transport: uses · Routes all NetworkManager calls through the D-Bus boundary.
- NM Module → NM Types: shares models · Uses domain types across the app and transport layers.
- NM Module → Auth: handles · Coordinates authentication flows.
- NM Module → Credentials: manages · Maps password and saved-connection data.
- Transport → D-Bus: via · D-Bus client transport implementation.
- Transport → NetworkManager: talks to · Communicates with the system NetworkManager service.
- Auth → Cache: consults · Uses local cache for remembered credentials when available.
- Auth → Credentials: produces · Builds auth payloads from credential data.
- UI Module → Network List: composes · Assembles the main screen.
- UI Module → Details: composes · Assembles detail panels.
- UI Module → Password Modal: composes · Assembles the password overlay.
- UI Module → Interface Select: composes · Assembles the interface picker.
- UI Module → Interfaces: composes · Assembles the interface browser.
- UI Module → QR Views: composes · Assembles the QR display view.
- UI Module → ratatui: renders with · Terminal UI rendering backend.
- App → Tokio: background work · Runs scans and connection attempts asynchronously.