F R A C T A L

Computation is most powerful when it mirrors life: distributed, adaptive, and collective.

Fractal is an exploration of "Empathetic Engineering." The system recognizes that every edge device is more than just a processor-it is a tool serving a human being. By moving training to the data, rather than the data to the server, Fractal respects the privacy of the individual while empowering the collective intelligence of the grid.

In this ecosystem, mobile devices are transformed into autonomous compute nodes that "feel" their environment-backing off when thermals rise or battery drops-ensuring that the machine's progress never comes at the cost of the human experience.

Fractal is architected as a hierarchical orchestration system. The root workspace manages the synergy between the FractalCore (Brain) and the FractalAndroid (Edge).

graph TD
    subgraph "FractalCore (Central Nervous System)"
        TS[Task Scheduler]
        FA[Federated Aggregator]
        TM[Tenant Manager]
        Budget[TFLOPs Monitor]
    end

    subgraph "Edge Intelligence (Grid Nodes)"
        C1[Android Node A]
        C2[Android Node B]
        CN[Android Node N]
    end

    subgraph "Persistence & Rewards"
        FS[(Firestore)]
        RM[Liquid MB Rewards]
    end

    C1 & C2 & CN <-->|Task Fetch / Weight Upload| TS
    TS --> Budget
    FA --> TS
    C1 & C2 & CN -->|Hardware Proof| RM
    RM --> FS

The lifecycle of a training task follows a fractal loop of distribution and convergence.

sequenceDiagram
    participant T as Tenant (Admin)
    participant S as FractalCore
    participant C as Android Client
    participant F as Firebase

    T->>S: Define Session (Config + TFLOPs)
    S->>S: Partition Data (Fractal Bins)
    Note over S: Tasks Queued per Tenant
    
    C->>S: GET /api/task (Device Hardware Proof)
    S-->>C: ActiveTask (Architecture + Bin Metadata)
    
    C->>C: Resource Check (Battery/Thermals)
    C->>S: Download Model + Bins
    C->>C: Execute On-Device Training (TFLite)
    C->>S: POST /upload (Local Checkpoint)
    
    S->>F: Credit "Liquid MBs" to Device ID
    
    Note over S: If N Clients Uploaded:
    S->>S: Federated Averaging (FedAvg)
    S->>S: Update Global Model

The project is organized to maintain strict separation of concerns between server orchestration and edge execution.

.
├── FractalApp/
│   └── FractalAndroid/      # Android Client (Kotlin/TFLite)
│       ├── app/             # Main Application Logic
│       ├── build/           # Generated Build Artifacts
│       └── ...
├── FractalCore/
│   └── src/
│       └── fractal_server/  # Python Flask Orchestrator
│           ├── global_model/# Global Weights Storage
│           ├── tenants/     # Tenant-specific Data Silos
│           └── server.py    # Main API & Aggregator
├── docs/
│   └── assets/              # Branding & Diagrams
└── private.envs/            # [PRIVATE] Sensitive Keys & Configs

The backend engine designed for multi-tenant isolation and deterministic aggregation.

• Tenant System: Independent data silos and compute budgets per user.
• TFLOPs Budgeting: Real-time monitoring of compute expenditures.
• FedAvg Engine: High-performance weight averaging using TensorFlow.
• Firestore Integration: Real-time synchronization of device registries and rewards.

A resource-aware execution environment for mobile devices.

• Synthesis Engine: Dynamically builds the training environment based on server metadata.
• Telemetry Gating: Monitors battery status, network type, and thermals to protect the host.
• Master Pipeline: An automated Fetch -> Download -> Train -> Upload -> Flush cycle.

• Python 3.10+ (for Core)
• Android Studio Jellyfish+ (for App)
• Firebase Account (Firestore enabled)

This repository uses a private sub-module for sensitive keys and configurations. To restore the environment:

1. Clone the repository including submodules:

   git clone --recursive https://github.com/Fractal-Compute-Orchestrations/FractalWorkspace

2. Navigate to the private environment directory:

   cd private.envs/Fractal

3. Run the restoration script to place keys and configs in their correct locations:

   .\restore.ps1

• Zero-Data Transfer: Raw training data never leaves the Android device. Only locally-computed weight checkpoints are transmitted to the server — the server never sees the underlying dataset.
• X-Auth-Token Authentication: Every protected endpoint is guarded by _get_auth(), which resolves identity exclusively from the X-Auth-Token request header. Tokens are issued via secrets.token_hex(32) at login, stored server-side in a thread-safe _token_store, and revoked on logout. No cookie fallback exists — a deliberate design decision that prevents session bleed across browser tabs, as each tab holds its own token in sessionStorage.
• Tenant Filesystem Isolation: Each tenant's training data, upload checkpoints, and global model checkpoint are stored under a physically separate directory tree (data/tenants/{username}/). There is no shared mutable path between tenants at the filesystem level.
• Task-ID–Bound Upload Validation: Client checkpoint uploads are validated against a _global_task_tenant_map keyed by task_Id. Uploads referencing an unknown or already-consumed task ID are rejected with 400 Unknown task_Id, preventing stale or replayed weight injection.