# arekkazu/wirfi architecture

> Architecture diagram of the GitHub repository arekkazu/wirfi, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/arekkazu/wirfi
- Repository: https://github.com/arekkazu/wirfi

## Overview

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: [`src/app.rs`](https://github.com/arekkazu/wirfi/blob/main/src/app.rs) (App), [`src/ui/mod.rs`](https://github.com/arekkazu/wirfi/blob/main/src/ui/mod.rs) (UI Module), [`src/nm/mod.rs`](https://github.com/arekkazu/wirfi/blob/main/src/nm/mod.rs) (NM Module), [`src/main.rs`](https://github.com/arekkazu/wirfi/blob/main/src/main.rs) (Main)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_main["Main<br/>entrypoint<br/>[main.rs]"]
  node_app["App<br/>orchestrator<br/>[app.rs]"]
  node_input["Input<br/>event mapping<br/>[input.rs]"]
end

subgraph group_nm["NetworkManager"]
  node_transport["Transport<br/>dbus client<br/>[transport.rs]"]
  node_nm_types["NM Types<br/>domain models<br/>[types.rs]"]
  node_auth["Auth<br/>[auth.rs]"]
  node_credentials["Credentials<br/>credential model<br/>[credentials.rs]"]
  node_nm_mod["NM Module<br/>integration facade<br/>[mod.rs]"]
end

subgraph group_ui["TUI"]
  node_ui_mod["UI Module<br/>presentation facade<br/>[mod.rs]"]
  node_network_list["Network List<br/>screen<br/>[network_list.rs]"]
  node_details_panels["Details<br/>panel<br/>[details_panels.rs]"]
  node_password_modal["Password Modal<br/>overlay<br/>[password_modal.rs]"]
  node_interface_select["Interface Select<br/>screen"]
  node_interfaces["Interfaces<br/>screen<br/>[interfaces.rs]"]
  node_qr_views["QR Views<br/>[qr_views.rs]"]
end

subgraph group_state["State"]
  node_error["Errors<br/>error model<br/>[error.rs]"]
  node_cache[("Cache<br/>local storage<br/>[cache.rs]")]
end

subgraph group_external["External"]
  node_zbus{{"D-Bus<br/>external service"}}
  node_networkmanager[("NetworkManager<br/>system service")]
  node_tokio{{"Tokio<br/>async runtime"}}
  node_ratatui{{"ratatui<br/>ui library"}}
end

node_main -->|"bootstraps"| node_app
node_main -->|"starts ui"| node_ui_mod
node_main -->|"initializes nm"| node_nm_mod
node_input -->|"dispatches"| node_app
node_app -->|"renders via"| node_ui_mod
node_app -->|"drives"| node_network_list
node_app -->|"drives"| node_details_panels
node_app -->|"opens"| node_password_modal
node_app -->|"routes"| node_interface_select
node_app -->|"routes"| node_interfaces
node_app -->|"shows"| node_qr_views
node_app -->|"requests"| node_nm_mod
node_app -->|"reads/writes"| node_cache
node_app -->|"propagates"| node_error
node_nm_mod -->|"uses"| node_transport
node_nm_mod -->|"shares models"| node_nm_types
node_nm_mod -->|"handles"| node_auth
node_nm_mod -->|"manages"| node_credentials
node_transport -->|"via"| node_zbus
node_transport -->|"talks to"| node_networkmanager
node_auth -->|"consults"| node_cache
node_auth -->|"produces"| node_credentials
node_ui_mod -->|"composes"| node_network_list
node_ui_mod -->|"composes"| node_details_panels
node_ui_mod -->|"composes"| node_password_modal
node_ui_mod -->|"composes"| node_interface_select
node_ui_mod -->|"composes"| node_interfaces
node_ui_mod -->|"composes"| node_qr_views
node_ui_mod -->|"renders with"| node_ratatui
node_app -.->|"background work"| node_tokio

click node_main "https://github.com/arekkazu/wirfi/blob/main/src/main.rs"
click node_app "https://github.com/arekkazu/wirfi/blob/main/src/app.rs"
click node_input "https://github.com/arekkazu/wirfi/blob/main/src/input.rs"
click node_error "https://github.com/arekkazu/wirfi/blob/main/src/error.rs"
click node_cache "https://github.com/arekkazu/wirfi/blob/main/src/cache.rs"
click node_transport "https://github.com/arekkazu/wirfi/blob/main/src/nm/transport.rs"
click node_nm_types "https://github.com/arekkazu/wirfi/blob/main/src/nm/types.rs"
click node_auth "https://github.com/arekkazu/wirfi/blob/main/src/nm/auth.rs"
click node_credentials "https://github.com/arekkazu/wirfi/blob/main/src/nm/credentials.rs"
click node_nm_mod "https://github.com/arekkazu/wirfi/blob/main/src/nm/mod.rs"
click node_ui_mod "https://github.com/arekkazu/wirfi/blob/main/src/ui/mod.rs"
click node_network_list "https://github.com/arekkazu/wirfi/blob/main/src/ui/network_list.rs"
click node_details_panels "https://github.com/arekkazu/wirfi/blob/main/src/ui/details_panels.rs"
click node_password_modal "https://github.com/arekkazu/wirfi/blob/main/src/ui/password_modal.rs"
click node_interface_select "https://github.com/arekkazu/wirfi/blob/main/src/ui/interface_select.rs"
click node_interfaces "https://github.com/arekkazu/wirfi/blob/main/src/ui/interfaces.rs"
click node_qr_views "https://github.com/arekkazu/wirfi/blob/main/src/ui/qr_views.rs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main,node_app,node_input toneBlue
class node_transport,node_nm_types,node_auth,node_credentials,node_nm_mod toneAmber
class node_ui_mod,node_network_list,node_details_panels,node_password_modal,node_interface_select,node_interfaces,node_qr_views toneMint
class node_error,node_cache toneRose
class node_zbus,node_networkmanager,node_tokio,node_ratatui toneIndigo
```

## Components

### Runtime

Startup, input normalization, and orchestration.

- [Main](https://github.com/arekkazu/wirfi/blob/main/src/main.rs): entrypoint · Program startup and wiring. · `src/main.rs`
- [App](https://github.com/arekkazu/wirfi/blob/main/src/app.rs): orchestrator · Central state machine coordinating UI, input, cache, and NM actions. · `src/app.rs`
- [Input](https://github.com/arekkazu/wirfi/blob/main/src/input.rs): event mapping · Normalizes terminal key events into app actions. · `src/input.rs`

### NetworkManager

DBus-backed NetworkManager integration and auth handling.

- [Transport](https://github.com/arekkazu/wirfi/blob/main/src/nm/transport.rs): dbus client · NetworkManager D-Bus transport boundary. · `src/nm/transport.rs`
- [NM Types](https://github.com/arekkazu/wirfi/blob/main/src/nm/types.rs): domain models · NetworkManager-facing data models for devices, APs, and connection state. · `src/nm/types.rs`
- [Auth](https://github.com/arekkazu/wirfi/blob/main/src/nm/auth.rs): auth flow · NetworkManager authentication and session credential handling. · `src/nm/auth.rs`
- [Credentials](https://github.com/arekkazu/wirfi/blob/main/src/nm/credentials.rs): credential model · Password and saved connection data abstractions. · `src/nm/credentials.rs`
- [NM Module](https://github.com/arekkazu/wirfi/blob/main/src/nm/mod.rs): integration facade · Top-level NetworkManager integration module wiring subcomponents. · `src/nm/mod.rs`

### TUI

Terminal screens and widgets.

- [UI Module](https://github.com/arekkazu/wirfi/blob/main/src/ui/mod.rs): presentation facade · Top-level TUI module wiring the screens and widgets. · `src/ui/mod.rs`
- [Network List](https://github.com/arekkazu/wirfi/blob/main/src/ui/network_list.rs): screen · Main scan-and-connect view. · `src/ui/network_list.rs`
- [Details](https://github.com/arekkazu/wirfi/blob/main/src/ui/details_panels.rs): panel · Device and access-point detail side panels. · `src/ui/details_panels.rs`
- [Password Modal](https://github.com/arekkazu/wirfi/blob/main/src/ui/password_modal.rs): overlay · Password entry dialog for protected networks. · `src/ui/password_modal.rs`
- [Interface Select](https://github.com/arekkazu/wirfi/blob/main/src/ui/interface_select.rs): screen · Initial chooser for wireless interfaces. · `src/ui/interface_select.rs`
- [Interfaces](https://github.com/arekkazu/wirfi/blob/main/src/ui/interfaces.rs): screen · Browser for available interfaces and their state. · `src/ui/interfaces.rs`
- [QR Views](https://github.com/arekkazu/wirfi/blob/main/src/ui/qr_views.rs): view · QR code display for stored WiFi credentials. · `src/ui/qr_views.rs`

### State

Local persistence and shared error handling.

- [Errors](https://github.com/arekkazu/wirfi/blob/main/src/error.rs): error model · Shared application error type and failure normalization. · `src/error.rs`
- [Cache](https://github.com/arekkazu/wirfi/blob/main/src/cache.rs): local storage · Local password and credential cache. · `src/cache.rs`

### External

Runtime dependencies and outside services.

- **D-Bus**: external service · NetworkManager communication transport.
- **NetworkManager**: system service · System WiFi and connection manager.
- **Tokio**: async runtime · Background worker and async task execution.
- **ratatui**: ui library · Terminal rendering framework.

## Connections

- 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.
