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
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.
 |
 |
 |
 |
| 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 |
 |
 |
 |
| 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. |
 |
 |
 |
| 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. |
 |
 |
 |
| 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. |
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 |
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
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 |
Workload paused until charging connected |
| Battery Temperature | Temp |
Execution paused until thermal normalization |
| Network Connectivity | Unmetered Wi-Fi Connected | Checkpoint upload deferred |
| Memory Pressure | System Memory Low == False | Batch buffer size throttled |
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)
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
| 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. |
- 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
# 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- 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.
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.