System Requirements Document for star-controller

1. Introduction

STAR CONTROLLER is an Android APK for a beginner user on a Samsung A03 (720x1600, 3 GB RAM, Android 11+) who wants to start and stop an allowed shell script on their own phone without a computer and without editing application code. The product is a control instrument, not a content app: it presents a green START control, a red STOP control, and a status indicator that is only allowed to read as active after the script has been proven to be running.

The audience is a non-technical, phone-only tinkerer who runs scripts through Brevent. The product intent is therefore trust, calm and honesty: the interface must never fake a running state, must report success or failure through Android notifications, must explain Android and Brevent permission limits truthfully, and must be buildable and installable directly from the phone using the easiest method available to a beginner.

The five accepted feature concepts are Control Center, Floating Bubble, Notification Controller, Module Configurator, and Local Web Controller. The accepted priority is explicit: Control Center with START and STOP is the first version, and the remaining features are added gradually after it succeeds.

2. System Overview

STAR CONTROLLER is delivered as a first-party Android application (APK) with a small companion backend that serves the Local Web Controller dashboard over the same Wi-Fi network. The Android app owns the instrument panel, the configuration of script location and START/STOP commands, the floating bubble overlay, the notification controls, and the honest status lamp. The backend owns the local web dashboard and the shared module state that both the phone and the same-Wi-Fi operator read.

Current actors are the Beginner Android User (Samsung A03 owner), the Module Configurator (script owner), and the Local Web Controller (same-Wi-Fi operator). Brevent is an external, provider-owned bridge: STAR CONTROLLER integrates with it only through official and compatible mechanisms where available, and reports honest failure and limitation information when it is not. The Android operating system owns notification permission, overlay permission, and local network reachability.

Accepted behavior in the current horizon: a green START and a red STOP control, a module status indicator that stays unverified until a command is confirmed, success/failure notifications, script location and START/STOP command configuration without editing application code, a draggable floating bubble usable over other apps, START/STOP from the notification panel, and a local web dashboard reachable from another device on the same Wi-Fi network.

Narrow exclusions: no root is used unless necessary; no active status is shown before the script is proven to be running; no mock-up-only implementation is acceptable; Brevent integration must not use unofficial or incompatible mechanisms; the generic indigo/blue-on-white SaaS template look is forbidden.

2a. Product Interpretation and Delivery Boundary

STAR CONTROLLER is delivered as a real, working Android application, not a visual mock-up. The phone is the primary surface: the user installs the APK directly on the Samsung A03, opens the app, and controls the module from the instrument panel. The floating bubble and the notification controls are additional first-party control surfaces that live on the same phone and are used while other apps are open or while the phone is locked to the notification shade.

The Local Web Controller is a first-party dashboard served by the app's companion backend and reached from another device on the same Wi-Fi network. It is an alternative control surface to the phone, not a replacement for it, and it depends on the phone and the other device being on the same network.

Brevent is an external, provider-owned bridge. STAR CONTROLLER does not own Brevent, does not bundle it, and does not claim to control it beyond what Brevent officially and compatibly exposes. Where Brevent cannot be reached through an official and compatible mechanism, the app reports the limitation honestly instead of simulating success.

Identity is application-owned. A first-use operator establishes access through self-service enrollment, and a returning operator verifies before protected control or configuration actions. This is required because module configuration and execution state are durable and must remain bound to the correct operator across sessions. Access to the Landing surface is anonymous; the protected control and configuration surfaces require the operator to be verified.

Current horizon: Control Center with START and STOP, plus the supporting configuration, notification, bubble, and local web surfaces described above. Future horizon: none accepted beyond the gradual addition of the already-listed feature concepts after Control Center succeeds.

2b. Source Content Inventory

Not applicable. No reference directive in this request declares a content_source, so no source content inventory is produced.

2c. Page Content and Component Coverage

Landing

• Information/state: anonymous first impression of STAR CONTROLLER; what the app does; the five control options; intended Samsung A03 use; honest Android and Brevent limitation summary; the current priority (Control Center first).
• Primary action: continue to establish access (self-service enrollment) or verify as a returning operator.
• Supporting actions: read the limitation summary; read the execution-path schematic.
• Domain entities: product description, feature concept list, limitation notes, execution-path nodes (App → Brevent → shell → script).
• Component responsibilities: wordmark header; 1px-stroke schematic rail of the four execution nodes; limitation note block; entry control to the access boundary.
• States: loading (static content, no network dependency); empty (not applicable, content is static); success (content rendered, entry control available); error (not applicable for static content); recovery (not applicable).

Login

• Information/state: anonymous access boundary; first-use enrollment form and returning verification form; explanation that access is needed to keep module configuration and execution state bound to the correct operator.
• Primary action: establish access on first use, or verify as a returning operator.
• Supporting actions: switch between first-use and returning modes; read why access is required.
• Domain entities: operator identity, credential, session.
• Component responsibilities: mode switch; enrollment fields; verification fields; submit control; inline validation messages.
• States: loading (submitting); empty (no credentials entered yet); success (access established, continue to Control Center); error (invalid or incomplete credentials, inline message, retry); recovery (re-enter credentials, retry).

Control Center

• Information/state: module name; live status lamp with exactly three states — amber UNVERIFIED (default, never green on assumption), green VERIFIED-RUNNING only after a confirmed exit code, red FAILED with the exit code printed beside it; ruled label/value instrument table (script path, last command, exit code, last run time, uptime); monospaced log strip with tabular timestamps.
• Primary actions: START (green confirmed state) and STOP (red).
• Supporting actions: read the label/value table; read the log strip; open Module Configurator; open the other control surfaces.
• Domain entities: module, script path, START command, STOP command, exit code, last run time, uptime, log entries.
• Component responsibilities: 96px status header with wordmark and 14px indicator lamp; START/STOP rocker pair as two equal-width 56px-tall controls sharing a single vertical hairline; segmented three-block mechanical progress counter during a held command; ruled label/value table; monospaced log strip pinned to the panel bottom.
• States: loading (command in progress, segmented counter stepping); empty (no command has been run yet, lamp amber UNVERIFIED, table shows no last run); success (lamp green VERIFIED-RUNNING, exit code shown, success notification); error (lamp red FAILED, exit code printed beside the lamp, failure notification, retry available); recovery (re-run START or STOP after a failure, lamp returns to amber UNVERIFIED until a new confirmation).

Module Configurator

• Information/state: current script file location; current START command; current STOP command; example values sh /sdcard/V8/vvipboost.sh and sh /sdcard/V8/stopvvipboost.sh; validation feedback.
• Primary action: save the script location and START/STOP commands.
• Supporting actions: edit each field; reset to the example values; read validation messages.
• Domain entities: script file location, START command, STOP command, saved configuration.
• Component responsibilities: script location field; START command field; STOP command field; save control; validation message area; example value hints.
• States: loading (saving); empty (no configuration saved yet, fields empty with example hints); success (configuration persisted, confirmation shown); error (invalid path or empty command, inline message, retry); recovery (correct the field and save again).

Floating Bubble

• Information/state: draggable floating control; current module status reflected on the bubble; overlay permission state.
• Primary actions: drag the bubble; tap to START or STOP.
• Supporting actions: read the bubble's status indication; open the Control Center from the bubble.
• Domain entities: bubble position, module status, overlay permission.
• Component responsibilities: draggable bubble surface; status indication on the bubble; tap target for START/STOP; overlay permission prompt when not granted.
• States: loading (command in progress); empty (overlay permission not granted, prompt shown); success (command confirmed, bubble reflects verified state); error (command failed, bubble reflects failed state, notification shown); recovery (grant overlay permission, retry).

Notification Controller

• Information/state: Android notification panel entry with START and STOP controls; current module status; notification permission state.
• Primary actions: START and STOP from the notification panel.
• Supporting actions: read the status shown in the notification; open the Control Center from the notification.
• Domain entities: notification, START action, STOP action, module status, notification permission.
• Component responsibilities: notification with START and STOP actions; status line; tap-through to Control Center; notification permission prompt when not granted.
• States: loading (command in progress); empty (notification permission not granted, prompt shown); success (command confirmed, notification updated to verified state); error (command failed, notification updated to failed state with exit code); recovery (grant notification permission, retry).

Local Web Controller

• Information/state: local web dashboard served by the companion backend; module status; START and STOP controls; the local network address to open from another device on the same Wi-Fi network.
• Primary actions: START and STOP from the web dashboard.
• Supporting actions: read module status; read the local address; refresh status.
• Domain entities: module status, START command, STOP command, local network address, session.
• Component responsibilities: status header; START/STOP controls; ruled label/value table; log strip; address display; access boundary for the same-Wi-Fi operator.
• States: loading (dashboard fetching status); empty (no command has been run yet, status unverified); success (command confirmed, status verified); error (command failed, exit code shown; or device not on the same Wi-Fi network, honest message); recovery (reconnect to the same Wi-Fi network, retry).

3. Functional Requirements

Each requirement is a distinct story point with provenance, lifecycle facts, and observable acceptance.

FR-1 — Build the STAR CONTROLLER Android APK (explicit) As a Beginner Android User (Samsung A03 owner), I should install and open a modern, minimalist, lightweight STAR CONTROLLER APK that is easy for a beginner to use on a Samsung A03.

• Trigger/input: the user installs the APK on the Samsung A03 and opens it.
• Observable result: the app opens to a simple, responsive interface sized for the A03 screen.
• Access state: anonymous entry is available on Landing; protected control requires verified access.
• Failure/recovery: if installation fails, the user follows the on-device build and install guide and retries.
• Continuation: the user proceeds to establish access and reach the Control Center.

FR-2 — Control Center dashboard with green START, red STOP, and status indicators (explicit) As a Beginner Android User (Samsung A03 owner), I should see a dashboard with a green START button, a red STOP button, and clear module status indicators.

• Trigger/input: the user opens the Control Center.
• Observable result: a green START control, a red STOP control, and a status indicator are visible.
• Access state: verified access required.
• Failure/recovery: if the status cannot be determined, the indicator stays amber UNVERIFIED rather than showing active.
• Continuation: the user presses START or STOP.

FR-3 — Floating Bubble draggable control (explicit) As a Beginner Android User (Samsung A03 owner), I should use a draggable floating button while other apps are open.

• Trigger/input: the user enables the bubble and drags it over another app.
• Observable result: the bubble moves with the drag and remains usable over other apps.
• Access state: verified access required; overlay permission required.
• Failure/recovery: if overlay permission is not granted, the app prompts for it and the bubble is unavailable until granted.
• Continuation: the user taps the bubble to START or STOP.

FR-4 — Notification Controller START and STOP (explicit) As a Beginner Android User (Samsung A03 owner), I should control START and STOP from the Android notification panel.

• Trigger/input: the user opens the notification panel and taps START or STOP.
• Observable result: the command is issued and the notification reflects the resulting status.
• Access state: verified access required; notification permission required.
• Failure/recovery: if notification permission is not granted, the app prompts for it and the notification controls are unavailable until granted.
• Continuation: the user reads the updated notification or opens the Control Center.

FR-5 — Module Configurator for script location and START/STOP commands (explicit) As a Module Configurator (script owner), I should set the script file location and the START and STOP commands without editing application code.

• Trigger/input: the user opens the Module Configurator and edits the script location, START command, and STOP command.
• Observable result: the configuration is saved and used by the Control Center, the bubble, the notification controls, and the local web dashboard.
• Access state: verified access required.
• Failure/recovery: if a field is invalid or empty, an inline message is shown and the save is rejected until corrected.
• Continuation: the user returns to the Control Center and runs the configured commands.

FR-6 — Local Web Controller over the same Wi-Fi network (explicit) As a Local Web Controller (same-Wi-Fi operator), I should open a local web dashboard from another device on the same Wi-Fi network to control the module and view its status.

• Trigger/input: the operator opens the local address from another device on the same Wi-Fi network.
• Observable result: the dashboard shows module status and provides START and STOP controls.
• Access state: verified access required for the operator.
• Failure/recovery: if the device is not on the same Wi-Fi network, the dashboard reports the limitation honestly and the operator reconnects and retries.
• Continuation: the operator starts or stops the module and reads the updated status.

FR-7 — Simple and responsive interface (explicit) As a Beginner Android User (Samsung A03 owner), I should use a simple and responsive interface.

• Trigger/input: the user interacts with any surface.
• Observable result: controls respond immediately and layout fits the A03 screen without overflow.
• Access state: applies to all surfaces.
• Failure/recovery: if a surface cannot render, the user returns to the Control Center.
• Continuation: the user continues the current task.

FR-8 — Phone-only use without a computer (explicit) As a Beginner Android User (Samsung A03 owner), I should use the app entirely on the Android phone without a computer.

• Trigger/input: the user performs all setup, configuration, and control on the phone.
• Observable result: no step requires a computer.
• Access state: applies to all surfaces.
• Failure/recovery: if a step appears to require a computer, the on-device guide provides the phone-only alternative.
• Continuation: the user completes the task on the phone.

FR-9 — Clear START, STOP, and status indicator controls (explicit) As a Beginner Android User (Samsung A03 owner), I should see clear START, STOP, and status indicator controls.

• Trigger/input: the user looks at any control surface.
• Observable result: START, STOP, and the status indicator are visually distinct and unambiguous.
• Access state: applies to all control surfaces.
• Failure/recovery: if the status is unknown, the indicator reads UNVERIFIED rather than active.
• Continuation: the user acts on the control.

FR-10 — Brevent integration through official and compatible mechanisms (explicit) As a Beginner Android User (Samsung A03 owner), I should have STAR CONTROLLER integrate with Brevent to run allowed scripts where possible through official and compatible mechanisms.

• Trigger/input: the user issues START or STOP.
• Observable result: the command is routed through the Brevent bridge when an official and compatible mechanism is available.
• Access state: verified access required.
• Failure/recovery: if no official and compatible mechanism is available, the app reports the limitation honestly and does not simulate success.
• Continuation: the user reads the honest result and decides whether to continue.

FR-11 — Example script commands (explicit) As a Module Configurator (script owner), I should be able to use the example commands sh /sdcard/V8/vvipboost.sh and sh /sdcard/V8/stopvvipboost.sh as the START and STOP commands.

• Trigger/input: the user enters or selects the example commands in the Module Configurator.
• Observable result: the example commands are accepted and used as the START and STOP commands.
• Access state: verified access required.
• Failure/recovery: if the script file is missing, the command fails and the failure is reported honestly.
• Continuation: the user corrects the path or command and retries.

FR-12 — Success or failure notification (explicit) As a Beginner Android User (Samsung A03 owner), I should see a notification when a command succeeds or fails.

• Trigger/input: a START or STOP command completes.
• Observable result: a notification reports success or failure, including the exit code on failure.
• Access state: notification permission required.
• Failure/recovery: if notification permission is not granted, the app prompts for it and the result is still shown in the Control Center.
• Continuation: the user reads the notification and continues.

FR-13 — No active status without proof (explicit) As a Beginner Android User (Samsung A03 owner), I should never see an active status if the script has not been proven to be running.

• Trigger/input: any command is issued.
• Observable result: the indicator stays amber UNVERIFIED until a confirmed exit code proves the script is running; only then does it become green VERIFIED-RUNNING.
• Access state: applies to all control surfaces.
• Failure/recovery: if proof is not obtained, the indicator remains UNVERIFIED or turns red FAILED with the exit code.
• Continuation: the user retries or investigates the failure.

FR-14 — No root unless necessary (explicit) As a Beginner Android User (Samsung A03 owner), I should use the app without root unless root is necessary.

• Trigger/input: the app performs its work.
• Observable result: the app does not require root for its accepted behavior.
• Access state: applies to all surfaces.
• Failure/recovery: if a specific operation genuinely requires root, the app explains this honestly rather than silently requesting it.
• Continuation: the user decides whether to proceed.

FR-15 — Honest explanation of Android and Brevent limitations (explicit) As a Beginner Android User (Samsung A03 owner), I should be told honestly about the limitations of Android permissions and Brevent.

• Trigger/input: the user reads the Landing surface or encounters a permission or Brevent limitation.
• Observable result: the limitation is explained in plain language.
• Access state: anonymous on Landing; available on protected surfaces.
• Failure/recovery: if a limitation blocks an action, the app explains why and what the user can do.
• Continuation: the user adjusts expectations or permissions and continues.

FR-16 — Complete code, project structure, and on-device build and install guide (explicit) As a Beginner Android User (Samsung A03 owner), I should receive complete code, the project structure, and a guide to build and install the APK directly from the Android phone.

• Trigger/input: the user follows the guide on the phone.
• Observable result: the APK is built and installed on the phone.
• Access state: not applicable to the app runtime.
• Failure/recovery: if a build step fails, the guide provides the beginner-friendly alternative.
• Continuation: the user opens the installed app.

FR-17 — Easiest build method for beginners (explicit) As a Beginner Android User (Samsung A03 owner), I should use the easiest build method for beginners.

• Trigger/input: the user chooses a build method.
• Observable result: the chosen method is the simplest available for a beginner on a phone.
• Access state: not applicable to the app runtime.
• Failure/recovery: if the method fails, the guide offers the next simplest option.
• Continuation: the user completes the build.

FR-18 — Real working implementation, not a mock-up (explicit) As a Beginner Android User (Samsung A03 owner), I should receive an implementation that actually works within Android's constraints, not only a mock-up display.

• Trigger/input: the user runs the app.
• Observable result: START and STOP actually issue commands and the status reflects real results.
• Access state: verified access required for control.
• Failure/recovery: if a constraint prevents execution, the app reports the real failure rather than a simulated success.
• Continuation: the user acts on the real result.

FR-19 — Priority: Control Center first, then gradual additions (explicit) As a Beginner Android User (Samsung A03 owner), I should get Control Center with START and STOP as the first version, with the other features added gradually after it succeeds.

• Trigger/input: the user uses the first version.
• Observable result: Control Center with START and STOP is functional first; the other feature concepts follow.
• Access state: verified access required.
• Failure/recovery: if Control Center does not succeed, the other features are not treated as delivered.
• Continuation: the user adopts the additional features as they arrive.

FR-20 — Self-service enrollment for a first-use operator (required_inference) As a Beginner Android User (Samsung A03 owner), I should establish access on first use through self-service enrollment when no external provisioning boundary is established.

• Trigger/input: the user opens the app for the first time and chooses to establish access.
• Observable result: an operator identity is created and the user reaches the protected surfaces.
• Access state: anonymous entry on Landing and Login; protected surfaces become available after enrollment.
• Failure/recovery: if enrollment fails, an inline message is shown and the user retries.
• Continuation: the user reaches the Control Center.

FR-21 — Returning verification before protected actions (required_inference) As a Beginner Android User (Samsung A03 owner), I should verify as a returning operator before protected control or configuration actions.

• Trigger/input: the returning user opens the app and enters credentials.
• Observable result: the user reaches the protected surfaces with their durable module configuration and execution state intact.
• Access state: anonymous entry on Login; protected surfaces available after verification.
• Failure/recovery: if verification fails, an inline message is shown and the user retries.
• Continuation: the user resumes control or configuration.

FR-22 — Persisted script location and START/STOP command configuration (required_inference) As a Module Configurator (script owner), I should have my script location and START/STOP command configuration persisted so it survives app restarts and is used by every control surface.

• Trigger/input: the user saves the configuration in the Module Configurator.
• Observable result: the configuration is stored and reused by the Control Center, the bubble, the notification controls, and the local web dashboard.
• Access state: verified access required.
• Failure/recovery: if saving fails, an inline message is shown and the user retries.
• Continuation: the user runs the configured commands.

FR-23 — Verified command execution before presenting an active status (required_inference) As a Beginner Android User (Samsung A03 owner), I should have the app verify command execution before presenting an active module status.

• Trigger/input: a START or STOP command completes.
• Observable result: the indicator becomes green VERIFIED-RUNNING only after a confirmed exit code; otherwise it stays amber UNVERIFIED or turns red FAILED.
• Access state: applies to all control surfaces.
• Failure/recovery: if verification cannot be obtained, the indicator does not show active.
• Continuation: the user retries or investigates.

FR-24 — Android notification permission and compatible notification-action handling (required_inference) As a Beginner Android User (Samsung A03 owner), I should grant notification permission so the Notification Controller and success/failure notifications work.

• Trigger/input: the user enables the Notification Controller or a command completes.
• Observable result: the notification with START and STOP actions is available and results are reported.
• Access state: notification permission required.
• Failure/recovery: if permission is denied, the app explains the limitation and the result is still shown in the Control Center.
• Continuation: the user grants permission or continues without the notification controls.

FR-25 — Overlay permission before using the Floating Bubble (required_inference) As a Beginner Android User (Samsung A03 owner), I should grant overlay permission before using the Floating Bubble.

• Trigger/input: the user enables the Floating Bubble.
• Observable result: the bubble becomes available over other apps.
• Access state: overlay permission required.
• Failure/recovery: if permission is denied, the app explains the limitation and the bubble stays unavailable.
• Continuation: the user grants permission or continues without the bubble.

FR-26 — Compatible, officially supported Brevent integration, otherwise honest failure (required_inference) As a Beginner Android User (Samsung A03 owner), I should have the app use a compatible, officially supported Brevent integration where available, and otherwise report honest failure and limitation information.

• Trigger/input: the user issues START or STOP.
• Observable result: the command is routed through the official and compatible Brevent mechanism when available; otherwise the app reports the limitation honestly.
• Access state: verified access required.
• Failure/recovery: if no official and compatible mechanism is available, the app does not simulate success and explains the limitation.
• Continuation: the user decides whether to continue.

FR-27 — Local network access and same-Wi-Fi reachability for the Local Web Controller (required_inference) As a Local Web Controller (same-Wi-Fi operator), I should have local network access and same-Wi-Fi reachability so the local web dashboard is usable from another device.

• Trigger/input: the operator opens the local address from another device on the same Wi-Fi network.
• Observable result: the dashboard loads and shows module status with START and STOP controls.
• Access state: verified access required for the operator.
• Failure/recovery: if the device is not on the same Wi-Fi network, the dashboard reports the limitation honestly and the operator reconnects and retries.
• Continuation: the operator controls the module and reads the updated status.

4. User Personas

Beginner Android User (Samsung A03 owner)

• Product context: a novice on a Samsung A03 (720x1600, 3 GB RAM, Android 11+) who wants to start and stop an allowed script without a computer and without editing code. They are not a developer and do not want to read source code to use the app.
• Primary goal: press START or STOP and know, honestly, whether the script actually ran.
• Distinct accepted responsibilities: open the app, establish access on first use, reach the Control Center, press the green START or the red STOP, watch the status indicator, and rely on success/failure notifications to know whether the script actually ran. They also enable the Floating Bubble and the Notification Controller when they want to control the module while other apps are open or from the notification panel.
• Relevant inputs or decisions: whether to press START or STOP; whether to grant notification permission; whether to grant overlay permission; whether to trust the status shown.
• Interactions with other accepted participants: they depend on the Module Configurator (script owner) having set the script location and START/STOP commands; they may be the same person. They depend on the Local Web Controller (same-Wi-Fi operator) only when they choose to control the module from another device. They depend on Brevent as an external bridge and on Android for permissions.
• Observable success: the indicator reads green VERIFIED-RUNNING only after a confirmed exit code, a success notification arrives, and the log strip shows the run; on failure, the indicator reads red FAILED with the exit code and a failure notification arrives.
• What makes this role different: this role is the operator of the instrument, not its configurator. Their work is a single decisive press and an honest reading of the result, and their trust depends on the app never showing active without proof.

Module Configurator (script owner)

• Product context: the person who sets up the module by choosing the script file location and the START and STOP commands through the app's configuration screen instead of editing application code, so the same app can drive their own allowed scripts.
• Primary goal: make the app drive their own allowed scripts without touching application code.
• Distinct accepted responsibilities: open the Module Configurator, enter or select the script file location, enter the START command and the STOP command (for example sh /sdcard/V8/vvipboost.sh and sh /sdcard/V8/stopvvipboost.sh), save the configuration, and correct invalid or empty fields.
• Relevant inputs or decisions: the script file location; the START command; the STOP command; whether to use the example values; whether a field is valid.
• Interactions with other accepted participants: they configure the module that the Beginner Android User operates; they may be the same person. Their saved configuration is used by the Control Center, the Floating Bubble, the Notification Controller, and the Local Web Controller.
• Observable success: the configuration is saved and reused by every control surface, and the configured commands run when START or STOP is pressed.
• What makes this role different: this role changes the module's definition rather than operating it. Their work is a durable configuration decision, and their success is measured by the configured commands actually being used everywhere.

Local Web Controller (same-Wi-Fi operator)

• Product context: a user who opens the app's local web dashboard from another device on the same Wi-Fi network to start and stop the module and view its status, as an alternative control surface to the phone itself.
• Primary goal: control the module and read its status from another device on the same Wi-Fi network.
• Distinct accepted responsibilities: open the local address from another device on the same Wi-Fi network, verify access, read module status, press START or STOP, and read the updated status and log.
• Relevant inputs or decisions: the local address; whether the device is on the same Wi-Fi network; whether to press START or STOP.
• Interactions with other accepted participants: they operate the same module the Beginner Android User operates, using the configuration the Module Configurator saved. They depend on the phone and the other device being on the same Wi-Fi network.
• Observable success: the dashboard loads, shows module status, and START or STOP produces a confirmed result reflected in the dashboard.
• What makes this role different: this role works from a second device over the local network rather than on the phone. Their work is remote control and status reading, and their success depends on same-Wi-Fi reachability.

5. Core User Flows

Flow A — First use and access establishment (Beginner Android User)

1. The user installs the STAR CONTROLLER APK on the Samsung A03 and opens it.
2. The app shows the Landing surface: the wordmark, the execution-path schematic rail (App → Brevent → shell → script), the five control options, the intended Samsung A03 use, and the honest Android and Brevent limitation summary.
3. The user reads the limitation summary and chooses to continue to establish access.
4. The app shows the Login surface in first-use mode. The user enters their enrollment details and submits.
5. Observable result: an operator identity is created and the user reaches the Control Center.
6. Failure/recovery: if enrollment fails, an inline message is shown and the user retries.
7. Continuation: the user reaches the Control Center with the status lamp amber UNVERIFIED.

Flow B — Configure the module (Module Configurator)

1. The user opens the Module Configurator from the Control Center.
2. The user enters the script file location and the START and STOP commands, using the example values sh /sdcard/V8/vvipboost.sh and sh /sdcard/V8/stopvvipboost.sh if they match their setup.
3. The user saves the configuration.
4. Observable result: the configuration is persisted and will be used by the Control Center, the Floating Bubble, the Notification Controller, and the Local Web Controller.
5. Failure/recovery: if a field is invalid or empty, an inline message is shown and the save is rejected until corrected.
6. Continuation: the user returns to the Control Center.

Flow C — Start the module (Beginner Android User)

1. The user opens the Control Center. The status lamp is amber UNVERIFIED because no command has been confirmed.
2. The user presses the green START control. The control depresses 2px and inverts to its signal colour within 90ms, and the segmented three-block progress counter steps discretely while the command is held.
3. The command is routed through the Brevent bridge when an official and compatible mechanism is available.
4. Observable result: on a confirmed exit code, the lamp flips to green VERIFIED-RUNNING in a single 120ms step, the label/value table shows the last command, exit code, last run time, and uptime, the log strip records the run with a tabular timestamp, and a success notification arrives.
5. Failure/recovery: if the exit code is not confirmed, the lamp stays amber UNVERIFIED or turns red FAILED with the exit code printed beside it, and a failure notification arrives. The user retries or investigates.
6. Continuation: the user leaves the module running or proceeds to stop it.

Flow D — Stop the module (Beginner Android User)

1. The user opens the Control Center with the lamp green VERIFIED-RUNNING.
2. The user presses the red STOP control. The control depresses 2px and inverts to its signal colour within 90ms, and the segmented counter steps while the command is held.
3. The command is routed through the Brevent bridge when an official and compatible mechanism is available.
4. Observable result: on a confirmed exit code, the lamp flips to amber UNVERIFIED (no longer running), the label/value table shows the STOP command and its exit code, the log strip records the run, and a success notification arrives.
5. Failure/recovery: if the exit code is not confirmed, the lamp turns red FAILED with the exit code printed beside it, and a failure notification arrives. The user retries.
6. Continuation: the user starts the module again or leaves it stopped.

Flow E — Control from the Floating Bubble (Beginner Android User)

1. The user enables the Floating Bubble. If overlay permission is not granted, the app prompts for it and the bubble stays unavailable until granted.
2. The user opens another app and drags the bubble to a comfortable position.
3. The user taps the bubble to START or STOP.
4. Observable result: the bubble reflects the resulting status, and a success or failure notification arrives.
5. Failure/recovery: if the command fails, the bubble reflects the failed state and the notification shows the exit code. The user retries from the bubble or opens the Control Center.
6. Continuation: the user continues in the other app.

Flow F — Control from the Notification Controller (Beginner Android User)

1. The user enables the Notification Controller. If notification permission is not granted, the app prompts for it and the notification controls stay unavailable until granted.
2. The user opens the notification panel and taps START or STOP.
3. Observable result: the command is issued and the notification updates to the resulting status; a success or failure notification arrives.
4. Failure/recovery: if the command fails, the notification shows the failed state with the exit code. The user retries or opens the Control Center.
5. Continuation: the user dismisses the panel and continues.

Flow G — Control from the Local Web Controller (Local Web Controller (same-Wi-Fi operator))

1. The operator confirms that the phone and their device are on the same Wi-Fi network.
2. The operator opens the local address shown by the app in a browser on their device.
3. The operator verifies access on the dashboard.
4. Observable result: the dashboard shows module status, the ruled label/value table, and the log strip, with START and STOP controls.
5. The operator presses START or STOP.
6. Observable result: the dashboard shows the confirmed result, and the phone's Control Center reflects the same state.
7. Failure/recovery: if the device is not on the same Wi-Fi network, the dashboard reports the limitation honestly; the operator reconnects and retries. If the command fails, the dashboard shows the exit code.
8. Continuation: the operator continues to monitor or control the module.

Flow H — Returning use (Beginner Android User)

1. The user reopens the app after a previous session.
2. The app shows the Login surface in returning mode. The user enters their credentials and verifies.
3. Observable result: the user reaches the Control Center with their durable module configuration and execution state intact.
4. Failure/recovery: if verification fails, an inline message is shown and the user retries.
5. Continuation: the user resumes control or configuration.

6. Visuals Colors and Theme

The creative direction is authoritative for this section. Muse: Dieter Rams. Headline: "Less, but better — a Braun-panel control room for scripts."

Mode: dark.

Colour tokens by role

Green and red are never used decoratively. Roughly 80% warm neutral ground, 15% panel surfaces, 5% saturated signal.

Typography

• Headings: Archivo at 700–900, uppercase, 0.08em tracking, 0.95 leading — a stencilled equipment label.
• Body: Fira Sans.
• Small caps labels: Fira Sans 600 at 11px with 0.14em tracking.
• Numerals: always tabular so counters and log timestamps do not jitter.
• Scale: 1.25 modular on a 4pt baseline — 12 / 14 / 16 / 20 / 25 / 31 / 39 / 49px.
• Mobile display for the hero wordmark: clamp(38px, 11vw, 49px). Desktop/web-controller display: clamp(49px, 5vw, 72px). Body copy stays 15–16px at every breakpoint; nothing readable drops below 14px.

Shape language

• 8px and 4px rounded-rectangle controls; 16px radius on the main instrument panel.
• 2px machined borders in #3A372F; hairline 1px rules in #8C877C at 30% opacity.
• No pills, no blobs, no soft-shadow cards.
• Depth from a single 1px top highlight (#3F3C33) plus a 4px hard offset shadow.
• Every circular element is a real gauge, never decoration.

Layout

• Strict 12-column modular grid, 16px gutters, 20px page margins at 375px, 24px at 768px, 32px at 1280px.
• Control Center is one tall instrument panel: status header row (module name, live dot, verified/unverified state) → START/STOP rocker pair as two equal-width 56px-tall controls with a shared hairline divider → ruled label/value table of module facts (script path, last run, exit code, uptime) → monospaced log strip.
• Everything aligns to the same left rule; nothing floats.
• At 1280px the same panel becomes a two-column layout with the log strip occupying the right third, still inside one bordered frame.

Imagery

Diagrammatic line art in the Rams tradition: a 1px-stroke schematic of the execution path (App → Brevent bridge → shell → script file), a labelled module block diagram, and small pictograms for permissions, Wi-Fi, and notification states. No photography, no illustration for its own sake, no clip art. The hero visual is the instrument panel itself plus the schematic, drawn in the same stroke weight as the UI rules.

7. Signature Design Concept

The public entry is not a marketing hero. The first screen is the live instrument panel filling the viewport, and the signature idea is the honesty lamp as the only saturated colour on the screen.

• A 96px-tall status header spans the full width: the module name in Archivo 900 uppercase on the left, and a 14px circular indicator lamp on the right that is amber #F5A623 and reads UNVERIFIED until a command is confirmed.
• Beneath the header, a horizontal schematic rail in 1px #8C877C shows the four execution nodes — App → Brevent → shell → script — with the active node filled with signal orange #E8590C as the command travels. This is the only animation on the first screen.
• Directly under the rail sit the two dominant elements: an equal-width START and STOP rocker pair, each 56px tall, START in signal orange with a green confirmed state and STOP in #D63A2F, separated by a single vertical hairline.
• Below them, a ruled label/value table runs edge to edge with 1px hairlines and tabular numerals: script path, last command, exit code, last run time, uptime — aligned in a single left rule like a Braun spec plate.
• The composition is a control panel, not a landing page: no centred headline, no subtext, no gradient, no floating card.

The concept recomposes only accepted content, states and controls: the module name, the three-state lamp, the START/STOP pair, the label/value table, the log strip, and the execution-path schematic.

8. Interaction Model & Motion Direction

Interaction Model: Static Motion Tempo: restrained Hero Dimensionality: flat

Landing Hero Motion Brief

• Focal subject: the live instrument panel itself, with the 14px honesty lamp and the 1px execution-path schematic rail as the composed first frame.
• Input → transformation → outcome thesis: the user presses START or STOP → the control depresses 2px and inverts to its signal colour within 90ms with a linear ease, and the active schematic node fills with signal orange as the command travels → the lamp flips in a single 120ms step to green VERIFIED-RUNNING only after a confirmed exit code, or to red FAILED with the exit code printed beside it.
• Motion vocabulary: instant, mechanical feedback only. Buttons depress 2px and invert to their signal colour within 90ms with a linear ease — no bounce, no spring. Status changes flip the indicator lamp and its label in a single 120ms step with no crossfade. A held command shows a 3-step segmented progress bar that advances discretely, like a mechanical counter, never a smooth spinner. Scroll reveals are absent; the panel is simply there.
• Composed first frame: the 96px status header with the wordmark and the amber UNVERIFIED lamp, the schematic rail with four labelled nodes, the START/STOP rocker pair sharing a single vertical hairline, and the ruled label/value table running edge to edge.
• Reduced-motion state: prefers-reduced-motion removes the 2px depress and keeps only the colour inversion; the segmented counter still steps discretely and the lamp still flips in a single step.

9. Non-Functional Requirements

• NFR-1 — Lightweight and smooth on a Samsung A03 (explicit): the app must run smoothly on a 720x1600, 3 GB RAM, Android 11+ device. Rationale: the brief names the Samsung A03 as the target device and asks for a lightweight app. Flat depth and restrained motion keep the APK small and the UI smooth.
• NFR-2 — Simple and responsive interface (explicit): controls respond immediately and layout fits the A03 screen without overflow. Rationale: the brief asks for a simple and responsive interface.
• NFR-3 — Phone-only operation (explicit): every setup, configuration, and control step must be completable on the Android phone without a computer. Rationale: the brief prioritizes use on an Android phone without a computer.
• NFR-4 — Honest status (explicit): the app must never present an active status without a confirmed exit code. Rationale: the brief forbids showing an active status if the script has not been proven to be running.
• NFR-5 — No root unless necessary (explicit): the app must not require root for its accepted behavior. Rationale: the brief forbids using root unless necessary.
• NFR-6 — Official and compatible Brevent integration (explicit): Brevent integration must use official and compatible mechanisms where possible, and must report honest failure and limitation information otherwise. Rationale: the brief requires official and compatible mechanisms and honest limitation reporting.
• NFR-7 — Real working implementation (explicit): the delivered implementation must actually work within Android's constraints, not only display a mock-up. Rationale: the brief forbids a mock-up-only implementation.
• NFR-8 — Beginner-friendly build (explicit): the build and install method must be the easiest available for a beginner on a phone. Rationale: the brief asks for the easiest build method for beginners.

• NFR-9 — Readable text and controls at every viewport (explicit, from the creative direction): headlines, wordmarks, labels, numbers, and controls stay entirely inside the viewport and their container at 375px, 768px and 1280px, wrapping or scaling to fit, and no other element covers any part of them. Rationale: the creative direction requires readable text and controls to stay whole at every viewport.
• NFR-10 — Notification and overlay permission handling (required_inference): the app must request and handle Android notification permission and overlay permission, and must explain the limitation honestly when either is denied. Rationale: the Notification Controller and the Floating Bubble cannot function without these permissions, and the brief requires honest limitation reporting.
• NFR-11 — Same-Wi-Fi reachability (required_inference): the Local Web Controller must be reachable from another device on the same Wi-Fi network, and must report the limitation honestly when the device is not on the same network. Rationale: the brief defines the Local Web Controller as controlling the module over the same Wi-Fi network.

10. Tech Stack

• Android application (APK) — the first-party client that owns the Control Center, Module Configurator, Floating Bubble, and Notification Controller surfaces. Chosen because the brief requires an Android APK installable directly on the phone.
• Kotlin with Jetpack Compose — the Android UI toolkit for the instrument panel, chosen for a lightweight, responsive interface on the Samsung A03. [Default — not specified by user]
• Android foreground service and notification APIs — for the Notification Controller and the success/failure notifications. Required by the accepted behavior.
• Android overlay (SYSTEM_ALERT_WINDOW) API — for the Floating Bubble. Required by the accepted behavior.
• Companion backend (Python/FastAPI) — serves the Local Web Controller dashboard and the shared module state over the same Wi-Fi network. Chosen because the Local Web Controller needs a server-side surface reachable from another device. [Default — not specified by user]
• Local storage on the device — persists the script location and START/STOP command configuration. Required by the accepted behavior.
• Docker / docker-compose — packages the companion backend for local deployment. [Default — not specified by user]
• Brevent — external, provider-owned bridge used only through official and compatible mechanisms. Not bundled or owned by STAR CONTROLLER.

11. Assumptions and Constraints

Assumptions

• A-1: The user has a Samsung A03 (720x1600, 3 GB RAM, Android 11+) and installs the APK directly on it. (explicit)
• A-2: Brevent is installed on the phone and exposes an official and compatible mechanism for running allowed scripts. If it does not, the app reports the limitation honestly. (explicit)
• A-3: The script files referenced by the configured commands exist at the configured location on the device. (explicit, from the example commands)
• A-4: The Local Web Controller operator has a second device on the same Wi-Fi network as the phone. (explicit)
• A-5: Application-owned identity is established through self-service enrollment on first use and verified on return, because module configuration and execution state are durable and must remain bound to the correct operator. (required_inference)

Constraints

• C-1: Do not show an active status if the script has not been proven to be running. (explicit)
• C-2: Do not use root unless necessary. (explicit)
• C-3: Brevent integration must use official and compatible mechanisms where possible. (explicit)
• C-4: Honestly explain the limitations of Android permissions and Brevent. (explicit)
• C-5: Do not provide only a mock-up display; the implementation must actually work within Android's constraints. (explicit)
• C-6: Priority order: Control Center with START and STOP is the first version; the other features are added gradually after it succeeds. (explicit)
• C-7: Prioritize use on an Android phone without a computer. (explicit)
• C-8: Use the easiest build method for beginners. (explicit)
• C-9: The generic indigo/blue-on-white SaaS template look is forbidden. (explicit, from the creative direction)
• C-10: Green and red are reserved exclusively for START and STOP actions and their confirmed results, never used decoratively. (explicit, from the creative direction)

12. Glossary

• STAR CONTROLLER: the Android APK and companion backend described in this document.
• Control Center: the main dashboard with the green START control, the red STOP control, and the module status indicator.
• Floating Bubble: the draggable floating control usable while other apps are open.
• Notification Controller: the START and STOP controls available from the Android notification panel.
• Module Configurator: the configuration surface for the script file location and the START and STOP commands.
• Local Web Controller: the local web dashboard served by the companion backend and reached from another device on the same Wi-Fi network.
• Brevent: the external, provider-owned bridge used to run allowed scripts through official and compatible mechanisms.
• Honesty lamp: the 14px circular indicator with exactly three states — amber UNVERIFIED (default), green VERIFIED-RUNNING only after a confirmed exit code, and red FAILED with the exit code printed beside it.
• UNVERIFIED: the default status state, shown when no command has been confirmed; never green on assumption.
• VERIFIED-RUNNING: the status state shown only after a confirmed exit code proves the script is running.
• FAILED: the status state shown when a command does not produce a confirmed exit code, with the exit code printed beside the lamp.
• Exit code: the numeric result returned by a command, used as the proof required before showing an active status.
• Segmented mechanical progress counter: the three discrete blocks that step during a held command, never a smooth spinner.
• Rocker pair: the two equal-width 56px-tall START and STOP controls sharing a single vertical hairline.

• Schematic rail: the 1px-stroke execution-path diagram showing App → Brevent → shell → script as four labelled nodes.
• Same-Wi-Fi operator: the Local Web Controller persona who controls the module from another device on the same Wi-Fi network.