FractalAndroid
Resource-Aware Edge Compute Node and Mobile Execution Engine
FractalAndroid is the distributed compute client and edge execution runtime for the Fractal decentralized intelligence framework.
Overview | Design Showcase | App UI Tour | WiFi Bank Rewards | Design Case Study | Architecture | Telemetry Gating | Lifecycle | Build & Setup
Overview
FractalAndroid turns Android mobile devices into autonomous, privacy-preserving compute nodes within the Fractal distributed network. Operating in coordination with the central server (FractalCore), the application executes localized machine learning workloads—including on-device federated training (TFLite) and partitioned batch dataset training—without exposing user data or degrading host device performance.
The client is designed with strict resource empathy: the engine continuously monitors physical hardware telemetry (SoC temperature, battery level, charging status, RAM pressure) and dynamically gates computation to guarantee zero impact on user experience or battery longevity.
Mobile UI Design & Hardware Showcase
 |
 |
 |
 |
| Active Compute Node Live training telemetry & diamond meter |
Model Training Metrics Performance curves & parameter transfer |
Platform Architecture Decentralized cloud & studio identity |
Dock Iconography Light & dark adaptive icon variants |
Mobile Application Interface
1. Onboarding, Device Authorization & Binding
 |
 |
 |
| Get Started: Platform onboarding introducing the decentralized compute harvesting paradigm. | Device Authorization: Firebase auth & hardware ID binding (`ANDROID_ID`, CPU, RAM). | Registered Info: Confirmed registration profile and assigned compute node telemetry. |
2. Node Fleet States & Real-Time Compute
 |
 |
 |
| Home (Standby / Inactive): Idle state awaiting task assignment with live hardware monitors. | Home (Active Compute): Active local training with pulsing fractal diamond indicator. | Node Settings & Preferences: Autonomous telemetry thresholds and charging policies. |
3. Telemetry, Analytics & Training Insights
 |
 |
 |
| Usage Insights: Time-series telemetry graphs for CPU, RAM, battery, and thermals. | Device Insights: Detailed hardware profiling with one-tap memory optimization. | Model Training: Live loss convergence curves, parameter transfer rates, and epoch progress. |
WiFi Bank & Bandwidth Rewards
Fractal transforms idle consumer mobile hardware into active decentralized compute infrastructure through a fair, transparent reward exchange:
- Edge Compute Contribution: When connected to power and unmetered Wi-Fi, the Android node executes quantized gradient descent or model slice inference.
- Liquid Bandwidth Credits (WiFi Bank): Every validated parameter checkpoint (
.ckpt) uploaded to FractalCore automatically credits liquid MBs to the device's account via the Firestore ledger. - Bandwidth Redemption: Users can redeem their accumulated data credits directly for high-speed Wi-Fi access or shared bandwidth pools.
 |
 |
 |
 |
 |
 |
 |
| 0.0 GB Initial / Empty |
0.5 GB Wave Rising |
0.7 GB Accumulating |
1.0 GB 50% Capacity |
1.5 GB 75% Capacity |
1.8 GB 90% Capacity |
2.0 GB Full Balance |
System Architecture
The client application follows a decoupled Model-View-ViewModel (MVVM) architecture with strict separation between UI telemetry rendering, hardware gating controllers, execution runtimes, and network synchronization layers.
graph TD
subgraph CentralServer ["FractalCore Control Plane"]
TaskDistributor["Task & Segment Dispatcher"]
ModelAggregator["Federated Model Aggregator"]
end
subgraph FractalAndroidClient ["FractalAndroid Compute Node"]
direction TB
subgraph PresentationLayer ["Presentation Layer (MVVM)"]
UI["Dashboard, Insights & Telemetry UI"]
VM["Telemetry & Task ViewModels"]
end
subgraph GatingLayer ["Hardware Governance"]
OperationControl["OperationControl (Thermal & SoC Gating)"]
TelemetrySensors["Battery, Thermal & Network Monitors"]
end
subgraph ExecutionLayer ["Compute Execution Engine"]
ImageTrainer["Image_Trainer (TFLite Engine)"]
DataManager["DataManager (ByteBuffer Batch Loader)"]
CheckpointMgr["CheckpointManager (.ckpt Serialization)"]
end
subgraph NetworkLayer ["Data & Transport Tier"]
ServerDAO["Server_DAO (Task Poller)"]
Transmitter["ModelTransmitter (TLS Weight Egress)"]
end
end
%% Wiring
TaskDistributor <-->|"REST HTTPS (/api/task/current)"| ServerDAO
ServerDAO --> OperationControl
OperationControl --> TelemetrySensors
TelemetrySensors --> VM
VM --> UI
OperationControl -->|"Permit: GRANTED"| ImageTrainer
ImageTrainer --> DataManager
ImageTrainer --> CheckpointMgr
CheckpointMgr --> Transmitter
Transmitter -->|"POST /api/model/upload"| ModelAggregator
Hardware Telemetry Gating
The client enforces strict multi-variable gating via OperationControl before and during computation:
| Telemetry Parameter | Operational Threshold | Action on Violation |
|---|---|---|
| Battery State-of-Charge | Level $\ge$ 50% or Charging == True | Workload paused until charging connected |
| Battery Temperature | Temp $\le$ 40.0 C | Execution paused until thermal normalization |
| Network Connectivity | Unmetered Wi-Fi Connected | Checkpoint upload deferred |
| Memory Pressure | System Memory Low == False | Batch buffer size throttled |
Execution Lifecycle
The lifecycle of a single federated compute round on the mobile client proceeds through automated telemetry checks, training execution, and encrypted checkpoint transmission.
sequenceDiagram
participant Server as FractalCore Server
participant Net as Server_DAO / Transmitter
participant Gate as OperationControl
participant Engine as Image_Trainer
participant Storage as CheckpointManager
Note over Net,Engine: Standby & Periodic Task Polling
Net->>Server: GET /api/task/current (device_id)
Server-->>Net: ActiveTask Payload (URLs + Hyperparams)
Net->>Gate: Request Execution Permit
Gate->>Gate: Sample Battery SoC, Thermals & Charging
alt Thermals > 40C or Battery < 50%
Gate-->>Net: Permit DENIED (Backoff & Sleep)
else Hardware Telemetry Healthy
Gate-->>Net: Permit GRANTED
end
Net->>Server: Download Model (.tflite) + Binary Data Bins
Net->>Engine: Initialize Weights & Segment Inputs
loop Epoch Loop
Engine->>Engine: Execute Local Gradient Descent Batch
Gate->>Gate: Continuous Thermal Check
alt Thermal Spike Detected
Gate->>Engine: Signal PAUSE (Preserve State)
Note over Engine: Wait for Thermal Normalization
Gate->>Engine: Signal RESUME
end
end
Engine->>Storage: Serialize Local Weight Checkpoint (.ckpt)
Storage->>Net: Pass Parameter Deltas
Net->>Server: POST /api/model/upload (task_Id, device_id, .ckpt)
Server-->>Net: 200 OK (Liquid MB Reward Credited)
Module Breakdown
FractalAndroid/
|-- app/src/main/java/
| |-- AppBackend/
| | |-- DataManager/ # Dataset binary segment parsing and caching
| | |-- LocalTrainingModule/ # TFLite Gradient Descent, Image_Trainer
| | |-- Network/ # Server_DAO, ModelTransmitter (TLS HTTP)
| | |-- ResourceManagement/ # OperationControl, Battery & Thermal Telemetry
| | |-- TaskContainer/ # ActiveTask DTOs and JSON serialization
| | `-- Validator/ # Accuracy validation & inference assertions
| |-- AppFrontend/
| | |-- Auth/ # Node Registration & Binding UI
| | |-- Home/ # Real-Time Compute & Training Dashboard
| | |-- Insights/ # Real-Time Telemetry & Hardware Charts
| | `-- Settings/ # Target Server URL & Threshold Configuration
| `-- AppGlobal/ # Cross-cutting Constants & Utility Helpers
|-- build.gradle.kts # Root Kotlin DSL Build Configuration
|-- app/build.gradle.kts # Application Module Build Configuration
`-- docs/ # Architecture Diagrams (.drawio) and Assets
Technical Pipeline Specifications
| Pipeline Stage | Java/Kotlin Implementation | Responsibility |
|---|---|---|
| Ingress | Server_DAO |
Polling task endpoints with exponential backoff and payload decoding. |
| Gating | OperationControl |
Real-time multi-variable telemetry gating (Thermal, Battery, RAM). |
| Execution | Image_Trainer |
On-device gradient calculation using optimized TFLite mobile kernels. |
| Data Parsing | DataManager / FileOperations |
Loading binary dataset batches into direct ByteBuffer structures. |
| Persistence | CheckpointManager |
Serialization of intermediate parameter matrices (.ckpt). |
| Egress | ModelTransmitter |
Encrypted transmission of .ckpt parameter updates to FractalCore. |
Development and Build
Prerequisites
- Android Studio: Version 2023.3.1 (Jellyfish) or newer
- Android SDK: Compile SDK 34, Min SDK 24
- JDK: Java 17 (recommended for Gradle 8+)
- Physical Device: Required for physical thermal and hardware sensor feedback loops
Build Workflow
# 1. Clone the repository git clone https://github.com/Fractal-Compute-Orchestrations/FractalAndroid.git cd FractalAndroid # 2. Build Debug APK ./gradlew assembleDebug # 3. Execute Unit Tests ./gradlew test # 4. Install and Run on Connected Device ./gradlew installDebug
Security & Privacy Guarantee
- Zero Data Exfiltration: Raw user data (images, local sensor feeds) remains confined to local storage. Only mathematical parameter checkpoints are sent to the server.
- Hardware Protection: Strict thermal and battery limits prevent device stress or accelerated battery degradation.
- TLS Egress Encryption: All communications with FractalCore occur over HTTPS/TLS.
Governance & Licensing
FractalAndroid is architected and owned by Ahmad Hassan (B-Ted).
- Contributing: See CONTRIBUTING.md
- Code of Conduct: See CODE_OF_CONDUCT.md
- Security Policy: See SECURITY.md
- License: Proprietary & Source-Available under the Fractal Proprietary Source-Available & Non-Commercial Restrictive License v3.0. All Rights Reserved. Commercial use strictly prohibited without written authorization.