Pi App UI Architecture
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The Pi App UI Architecture is designed to support a real-time audio visualizer and speaker interface running on embedded hardware, specifically the Raspberry Pi Zero 2 W. The system utilizes Flutter and the flutter-pi embedder to drive an HDMI display via DRM/KMS, bypassing standard X server or Wayland environments. This architecture is optimized for performance on resource-constrained ARMv7 hardware while maintaining a modern, reactive user interface managed by the BLoC pattern.
Sources: CLAUDE.md:15-22, README.md:1-12
The application acts as a WebSocket server, receiving real-time data from a companion phone app. This data is converted into specific UI states that drive a high-performance visualizer, track metadata displays, and system status indicators.
Sources: CLAUDE.md:25-30, README.md:24-30
Core UI Components and State Management
The UI is built using a "BLoC-per-feature" pattern. Each major UI section is tied to a specific BLoC that handles incoming WebSocket events and produces immutable states for the Flutter widget tree.
UI Feature Modules
The architecture divides the interface into several key visual and functional components:
| Component | Description | State Provider |
|---|---|---|
| Visualizer | High-speed FFT frequency bar rendering. | VisualizerBloc |
| Connection Banner | Displays status of the WebSocket client connection. | ConnectionBloc |
| Now Playing Bar | Shows track metadata, album art, and progress. | NowPlayingBloc |
| Home Screen | The primary layout container for all features. | N/A |
Sources: CLAUDE.md:52-57, README.md:43-52
Data Flow for UI Updates
The Pi app hosts a WebSocket server on port 8080. Data received from the network flows through a shared stream which is then dispatched to specific BLoCs based on the message type.
This diagram illustrates the unidirectional data flow from the WebSocket server through the BLoC layer to the UI components.
Sources: CLAUDE.md:25-30, README.md:32-41
Rendering and Optimization
To achieve smooth animations on the Pi Zero 2 W's limited hardware, the visualizer bypasses standard Flutter animation controllers.
Custom Visualizer Rendering
The visualizer utilizes a CustomPainter to draw directly to the Flutter Canvas. It renders FFT (Fast Fourier Transform) frequency bars at the same rate as the incoming WebSocket data (~30–60 Hz). This approach minimizes overhead by avoiding the standard widget build cycle for every frame of the audio animation.
Sources: README.md:54-58
Critical Implementation Details
- Naming Conflicts: The UI code must explicitly hide
ConnectionStatewhen importingpackage:flutter/material.dartto avoid conflicts withdart:async. - Target Architecture: The UI is compiled specifically for
armv7(32-bit) to ensure compatibility with the Pi Zero 2 W. - Embedded Environment: The
flutter-pitool is used for the build, ensuring the UI renders via DRM/KMS without an X server.
Sources: CLAUDE.md:17-23, CLAUDE.md:44-50
Hardware and Platform Integration
The UI architecture is closely coupled with the underlying Linux system and hardware via specific build configurations and upcoming GPIO integrations.
Build and Deployment Configuration
The build process for the Linux target is managed through CMake, which handles the inclusion of the Flutter library and AOT (Ahead-of-Time) compilation for performance.
The build system ensures all required Flutter engine components and compiled application code are bundled for the Linux environment.
Sources: apps/pi_app/linux/CMakeLists.txt:59-65, apps/pi_app/linux/CMakeLists.txt:110-120
Resource Specifications
| Requirement | Value | Source |
|---|---|---|
| SDK Version | ^3.11.5 | apps/pi_app/pubspec.yaml:31 |
| Target Architecture | armv7 | CLAUDE.md:19 |
| Flutter Version | 3.41.9 stable | CLAUDE.md:21 |
| Hardware | Pi Zero 2 W | README.md:15 |
Summary
The Pi App UI Architecture provides a specialized, high-performance interface for an embedded audio device. By combining the flutter_bloc state management pattern with direct CustomPainter rendering, the system achieves real-time visual feedback on low-power hardware. The architecture is defined by its reliance on a WebSocket-driven data flow and the flutter-pi embedder for efficient rendering on Raspberry Pi Linux environments.