Files
server-control-app/docs/superpowers/specs/2026-11-18-remote-device-trigger-app-design.md
T

129 lines
6.8 KiB
Markdown
Raw Normal View History

# Remote Device Trigger Android Application Design
## 1. Intent and Context
The user needs a dedicated mobile trigger application on Android to manage and control multiple remote machines (e.g., home lab servers, remote Debian or Pop!_OS nodes). The application provides an immediate, mistake-resistant control interface featuring three large buttons for each device: **Power On**, **Power Off**, and **Reboot**.
Devices are organized in a horizontal swipe interface. Device configuration URLs are fetched dynamically from a JSON file hosted in a Cloudflare R2 bucket, and critical commands (Power Off, Reboot) authenticate using a device-specific `secretKey`.
---
## 2. Goals, Non-Goals, and Anti-Goals
### Goals
- **Clear, Large Touch Targets**: Three huge, high-contrast, color-coded buttons (Power On, Power Off, Reboot) that are easy to tap accurately on a smartphone.
- **Multi-Device Horizontal Swiping**: A smooth horizontal pager allowing users to swipe left/right between devices, with visible page indicators.
- **Dynamic Configuration via Cloudflare R2**: Dedicated "Add Device" tab/card that takes a Cloudflare R2 JSON URL, fetches the endpoint mapping (`poweron`, `poweroff`, `reboot`), and configures the device.
- **Secure Request Dispatch**: Send HTTP POST requests using OkHttp with the `X-Secret-Key` header and JSON body `{"node": "<node>"}`.
- **Reliable Local Persistence**: All added devices and their configurations persist locally across application launches using `SharedPreferences`.
- **Immediate User Feedback**: Visual feedback for in-flight requests (loading indicators) and clear Toast / snackbar messages reporting HTTP status (e.g., `200 OK`, `Shutting down...`, or error details).
### Non-Goals
- Complex user account login or cloud synchronization across multiple phones (configurations are stored locally on the device).
- Real-time device telemetry / hardware sensor monitoring (CPU/RAM graphs); this is strictly a power-state remote trigger.
### Anti-Goals
- Cluttered, small text-heavy UI that makes hitting power buttons difficult or error-prone.
- Blocking the UI thread during network calls.
- Hardcoding endpoints and secret keys inside the application binary.
---
## 3. Constraints
- **Platform**: Android (minSdk 24, targetSdk 34) ensuring wide compatibility with virtually all modern Android phones.
- **Directory**: Must be placed in `/home/creserver/Desktop/Vaishno_workspace/experiments/exp-app`.
- **Language & UI Toolkit**: Kotlin with modern Jetpack Compose and Material 3.
- **Networking**: OkHttp for asynchronous HTTP requests and robust header/timeout handling.
- **Endpoint Structure**: Cloudflare R2 JSON contains URLs keyed by action (handling `poweron`, `poweroff`, `reboot` with flexible key parsing).
- **Authentication**: `X-Secret-Key` header passed with Power Off and Reboot requests, plus JSON body payload containing the node identifier and secret key.
---
## 4. Approaches Considered
1. **Modern Jetpack Compose Native App (Selected)**
- *Architecture*: Single Activity using Jetpack Compose with `HorizontalPager`, Material 3 components, OkHttp, and Gson.
- *Why chosen*: Cleanest declarative code, zero XML layout bloat, modern touch animations, responsive layouts with custom huge buttons, and straightforward state management.
2. **Classic ViewPager2 + XML Layouts**
- *Why rejected*: Significant boilerplate across XML layouts, RecyclerView adapters, and ViewBinding.
3. **Android WebView Hybrid**
- *Why rejected*: Unnecessary web engine overhead, less responsive touch/swipe feel, and inferior native integration.
---
## 5. Architectural and Behavioral Design
### 5.1 Navigation & Screen Flow
- Uses `HorizontalPager` with `n + 1` pages:
- Pages `0` to `n - 1`: Individual configured device trigger cards.
- Page `n`: Dedicated "+ Add Device" card.
- A horizontal page indicator (dots) at the bottom or top of the screen displays the current position and total pages.
- Header contains an app bar with the application title ("Device Trigger") and an option to delete/edit the currently selected device.
### 5.2 Device Screen (Pages 0 .. n-1)
- **Header**: Device Name (large bold font) and Node tag (e.g. `debian`).
- **Control Buttons**:
- **Power On** (Green `#2E7D32`): Sends request to `poweron` URL.
- **Reboot** (Amber/Orange `#EF6C00`): Prompts a quick confirmation sheet/dialog ("Are you sure you want to reboot [Device]?") -> on confirm, sends POST request to `reboot` URL with `X-Secret-Key`.
- **Power Off** (Red `#C62828`): Prompts a quick confirmation sheet/dialog ("Are you sure you want to power off [Device]?") -> on confirm, sends POST request to `poweroff` URL with `X-Secret-Key`.
- **Status Display**: A compact status card showing last action result (timestamp, response code, message) and loading progress bar when a request is active.
### 5.3 Add Device Screen (Last Page)
- Form fields:
- **Device Name** (e.g., "Home Server Debian")
- **Node Identifier** (e.g., "debian" or "pop-os")
- **Cloudflare R2 JSON URL** (e.g., `https://.../endpoints.json`)
- **Secret Key** (e.g., `Carbon@12` - with show/hide password toggle)
- Actions:
- **Fetch & Save**:
1. Downloads JSON from the provided Cloudflare R2 URL.
2. Validates that required action URLs exist (`poweroff`, `reboot`, and `poweron`).
3. Saves device to local persistent storage.
4. Automatically scrolls to the newly created device tab.
### 5.4 Data Storage & Models
- `DeviceConfig`:
- `id: String` (UUID)
- `name: String`
- `node: String`
- `secretKey: String`
- `r2Url: String`
- `powerOnUrl: String`
- `powerOffUrl: String`
- `rebootUrl: String`
- `DeviceRepository`:
- Serializes and stores `List<DeviceConfig>` in `SharedPreferences` via Gson.
- Provides reactive State / Flow of devices.
### 5.5 Cloudflare R2 JSON Format
The expected JSON format fetched from Cloudflare R2:
```json
{
"poweron": "https://cosmos.linuxguy.space/poweron",
"poweroff": "https://cosmos.linuxguy.space/poweroff",
"reboot": "https://cosmos.linuxguy.space/reboot"
}
```
*Note: Parser is resilient to key case variations (`powerOn`, `power_on`, `poweroff`, etc.).*
### 5.6 Network Request Specification
- **Client**: `OkHttpClient` with 15-second connect/read timeouts.
- **Power Off, Reboot, and Power On**:
- Method: `POST`
- Headers:
- `Content-Type: application/json`
- `X-Secret-Key: <device.secretKey>`
- Body:
```json
{
"node": "<device.node>"
}
```
- Both header (`X-Secret-Key`) and body (`{"node": "..."}`) match the server configuration and snippet provided.
---
## 6. What Is Left to the Builder
- Visual styling polish: button elevation, corner radius (16dp), vibrant Material3 color theming, and dark mode support.
- Optional preloaded demo/sample device for first-time onboarding if storage is empty.
- Gradle build and wrapper configuration to ensure clean standalone compilation.