Application Architecture

LuCI Mobile is a cross-platform Flutter application that manages OpenWrt routers. The app communicates with routers using the LuCI RPC (Remote Procedure Call) protocol to perform administrative tasks, monitor system health, and configure network settings.

Sources: README.md:12-14, pubspec.yaml:1-5

Tech Stack and Dependencies

The application uses the Flutter framework with Dart 3.8.1. It relies on a reactive state management approach and specific platform integrations for security and background tasks.

Core Frameworks

• Flutter & Dart: Provides the UI framework and programming language.
• Riverpod: Manages application state and dependency injection.
• Dio: Handles HTTP/HTTPS networking requests to the router's RPC interface.

Data Storage and Utilities

• Flutter Secure Storage: Encrypts and stores router credentials and profiles locally on the device.
• Fl Chart: Renders interactive charts for performance metrics.
• Workmanager & Local Notifications: Executes background monitoring and alerts users of network changes.

Sources: pubspec.yaml:31-48, README.md:50-52

Component Communication Flow

The app functions as a client-side interface that interacts directly with the OpenWrt router. No intermediary servers or analytics SDKs are involved in the data path.

The diagram shows the direct communication path between the mobile device and the router, emphasizing local credential storage and the lack of external cloud dependencies.
Sources: README.md:14-16, README.md:50-53, PRIVACY_POLICY.md:16-24

Platform Architecture

Android Implementation

The Android side uses Kotlin for its MainActivity. It implements modern "Edge-to-Edge" display logic by manipulating WindowInsetsControllerCompat. The manifest declares permissions for internet access and runtime notifications for background monitoring.

Sources: android/app/src/main/kotlin/com/cogwheel/LuCIMobile/MainActivity.kt:14-36, android/app/src/main/AndroidManifest.xml:2-6

Router Interface Requirements

For the architecture to function, the target router must have specific LuCI modules installed. These modules expose the necessary ubus objects for the app to query.

Sources: README.md:85-93

Data Management Logic

Configuration and Safety

When editing router settings, the app employs a specific protocol to prevent loss of connectivity.

1. Apply-with-Rollback: The app sends a configuration change.
2. Confirmation Loop: The phone must confirm the change within a specific time window.
3. Automatic Rollback: If the phone cannot confirm (e.g., due to a broken Wi-Fi link), the router restores the previous configuration.

Sources: README.md:44-48

Security Architecture

• Encryption: All sensitive credentials reside in the device's secure enclave.
• Certificate Handling: The app supports HTTPS and allows users to manually trust self-signed certificates after fingerprint verification.
• Direct Interaction: Data stays within the local network or the user's VPN tunnel.

Sources: PRIVACY_POLICY.md:38-44, README.md:50-52

Code Quality Standards

The project enforces strict linting and analysis through analysis_options.yaml. It uses a phased adoption strategy for rules, prioritizing resource management and error handling.

The project requires all contributions to pass flutter analyze with fatal infos enabled, ensuring high code consistency.
Sources: analysis_options.yaml:29-76, CONTRIBUTING.md:46-50

Build and Release Process

The project uses a bash-scripted release workflow that automates versioning and tagging.

The application architecture prioritizes local privacy and direct router control, utilizing Flutter's ecosystem to provide a modern interface for legacy OpenWrt RPC systems.