Skip to content

Latest commit

 

History

History
128 lines (99 loc) · 4.93 KB

ARCHITECTURE.md

File metadata and controls

128 lines (99 loc) · 4.93 KB

Framework System TUI: Architecture

Last updated: August 2025

Overview

Framework System TUI is a Rust-based dashboard that controls and monitors Framework laptop hardware from a terminal interface. It provides real-time data and interactive controls, organized into UI panels, using the ratatui library, and connects to hardware via the framework_lib crate.

Architectural Goals

  • Separation of Concerns: UI logic (App) and hardware interface (Framework) are strictly isolated.
  • Periodic Polling: Hardware status is updated at a fixed interval.
  • Panelized UI: Each type of hardware info/control is presented in a dedicated TUI panel.
  • Error Handling: Uses color-eyre throughout for robust reporting.

Module Overview

Module Path Purpose
Main src/main.rs App entrypoint. Sets up TUI environment, runs App.
App src/app.rs Event/render loop. Owns Framework; handles UI, input.
Framework src/framework.rs Manages hardware polling. Wraps EC and telemetry.
FrameworkInfo src/framework/info.rs Aggregates all hardware data for UI panels.
Tui & Components src/tui/ Panels, layout, input handling in TUI.

Data & Control Flow

High-Level

  1. App Startup: main.rs sets up terminal and starts App.
  2. Event Loop: App periodically polls hardware via Framework.
  3. Framework Polling: Framework collects hardware info at interval, parses state to FrameworkInfo.
  4. UI Panels: App renders state for distinct panels (battery, privacy, lighting, SMBIOS, PD ports etc).
  5. User Actions: Keyboard input dispatched to App, which may trigger hardware mutations via Framework.

Component Diagram

graph TD
    Main["main.rs: main()"]
    App["app.rs: App"]
    Framework["framework.rs: Framework"]
    Info["framework/info.rs: FrameworkInfo"]
    Tui["tui/"]
    Hardware["framework_lib (HW APIs)"]

    Main --> App
    App --> Framework
    Framework --> Info
    Info --> Tui
    Framework -->|polls| Hardware
    App --> Tui
    Tui -->|renders| User["User"]
    User --> App
Loading

Event Sequence

sequenceDiagram
    participant User
    participant Terminal
    participant App
    participant Framework
    participant HW
    User->>Terminal: Keyboard Input
    Terminal->>App: Key Events
    App->>Framework: poll_if_needed()
    Framework->>HW: Query hardware APIs
    HW-->>Framework: Return telemetry
    Framework-->>App: FrameworkInfo (snapshot)
    App-->>Terminal: Render UI
Loading

Periodic Polling

  • Framework polls hardware at fixed poll_interval.
  • Polling gathers:
    • Battery, charge %, power
    • Privacy status (cam/mic)
    • Brightness (keyboard, fingerprint)
    • SMBIOS info
    • PD ports
  • State stored in FrameworkInfo then visualized by App.

Component Details

Main (src/main.rs)

  • Entry point.
  • Sets up color-eyre, initializes ratatui, runs App::run().

App (src/app.rs)

  • Owns Framework and Tui.
  • Handles event loop:
    • Polls Framework for updates.
    • Renders info in panels.
    • Handles keyboard input, dispatches actions (quit, set charge limit, adjust brightness).

Framework (src/framework.rs)

  • Wraps underlying EC API (CrosEc from framework_lib).
  • Exposes hardware mutation methods (set charge limit, set brightness).
  • Polls all hardware data, collects into FrameworkInfo.
  • Decoupled from UI logic.

FrameworkInfo (src/framework/info.rs)

  • Captures all hardware states as fields.
  • Passed to TUI panels for display.

TUI (src/tui/)

  • Panels implemented in submodules:
    • Battery, Charge, Privacy, SMBIOS, Brightness, PD Ports, Footer, Title
  • Input routing, layout management, rendering via ratatui.

Key Data Structures

  • App (owns Framework, Info, TUI, controls lifecycle)
  • Framework (owns hardware abstraction, polling logic)
  • FrameworkInfo (complete telemetry snapshot for UI)
  • Tui and panel objects

Extensibility

  • New hardware features added by extending FrameworkInfo and panel submodules.
  • Platform independence maintained by isolating hardware logic in Framework.

License

Licensed under the terms detailed in Cargo.toml.