# featurecloud/featurecloud architecture

> Architecture diagram of the GitHub repository featurecloud/featurecloud, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/featurecloud/featurecloud
- Repository: https://github.com/featurecloud/featurecloud

## Overview

##### Project type and purpose
- This is an open-source Python platform for privacy-preserving federated learning (“FeatureCloud”).
- It provides:
- A CLI and HTTP API to manage a central controller.
- An “engine” for federated-app development (states & transitions).
- A workflow layer for non-linear orchestration of federated apps.
- Core use cases:
- Researchers/operators launch a controller, spin up federated-learning runs, monitor traffic & results.
- Developers build “FeatureCloud apps” (Docker images of state machines), publish to the FC App Store.

##### File structure
- Top level:
- FeatureCloud/api – API & CLI (command-line interface) plus “imp” (HTTP request implementation)
- FeatureCloud/app – the engine package (App & State classes, transition logic)
- FeatureCloud/workflow – orchestration layer, non-linear workflows
- tests, docs, CI configs, setup.py, build & publish scripts
- Patterns & modules:
- CLI under api/cli
- HTTP controller client under api/imp
- Core engine under app/engine
- Workflow definitions under workflow/
- Deployment artifacts: Dockerfile templates (in sample apps), build.sh/publish.sh, setup.cfg for pip packaging

##### README for insights
- The README outlines:
- CLI commands for controller management, app build/download/publish, test runs, workflow runs
- “app” module with App/State abstractions for local compute
- “workflow” for chaining apps in flexible graphs
- Key technologies: Python, Docker, HTTP, pip package, external Docker registry (FeatureCloud.ai)

a. Main components
- CLI Tool (FeatureCloud/api/cli)
- HTTP Client (FeatureCloud/api/imp)
- Controller Service (central orchestration engine)
- Docker Registry (FC App Store)
- Federated App Instances (containerized apps built via FeatureCloud/app)
- Workflow Orchestrator (FeatureCloud/workflow)
- Data Store / Controller DB (for metadata, logs, test results)
b. Relationships & interactions
- User runs CLI → sends commands via HTTP Client → Controller Service
- Controller pulls/pushes images to Docker Registry
- Controller spawns multiple App Instances as Docker containers
- App Instances execute State logic (via Engine package)
- Workflow layer interacts with Controller to chain multi-app runs
- Controller records status & traffic to Data Store; CLI queries this store
c. Architectural patterns & design principles
- Client-Server (CLI/HTTP client ↔ Controller)
- Plugin/State-Machine pattern (apps register states/transitions)
- Containerized microservices (each app instance in its own Docker container)
- Orchestration layer (controller + workflow engine) for distributed coordination
- Separation of concerns: API/CLI, orchestration, compute engine, workflow
d. Relevant technologies/frameworks/libraries
- Python 3.x, click (for CLI), requests (HTTP imp), Docker SDK/CLI
- pip packaging (setup.py, setup.cfg)
- CircleCI for CI/CD, sphinx for docs in docs/

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Subgraphs
    subgraph "User Interface" 
        CLI["CLI Tool"]:::frontend
        Workflow["Workflow Orchestrator"]:::frontend
    end

    subgraph "API Layer"
        HTTPClient["HTTP Client"]:::backend
    end

    subgraph "Orchestration Layer"
        Controller["Controller Service"]:::backend
    end

    subgraph "Compute Layer"
        DockerEngine["Docker Engine"]:::compute
        AppInstances["App Instances"]:::compute
    end

    subgraph "Storage & Registry"
        DockerRegistry["Docker Registry"]:::external
        DataStore["Data Store"]:::backend
    end

    %% Connections
    CLI -->|"CLI commands"| HTTPClient
    Workflow -->|"workflow commands"| Controller
    HTTPClient -->|"REST API calls"| Controller
    Controller -->|"docker pull/push"| DockerRegistry
    Controller -->|"spawn containers"| DockerEngine
    DockerEngine -->|"run state machines"| AppInstances
    Controller -->|"record metadata"| DataStore
    AppInstances -->|"log results"| DataStore
    CLI -->|"query status"| DataStore

    %% Click events
    click CLI "https://github.com/featurecloud/featurecloud/blob/master/FeatureCloud/api/cli/__main__.py"
    click HTTPClient "https://github.com/featurecloud/featurecloud/blob/master/FeatureCloud/api/imp/__init__.py"
    click Controller "https://github.com/featurecloud/featurecloud/blob/master/FeatureCloud/api/imp/controller/commands.py"
    click DockerEngine "https://github.com/featurecloud/featurecloud/blob/master/FeatureCloud/app/engine/__init__.py"
    click AppInstances "https://github.com/featurecloud/featurecloud/blob/master/FeatureCloud/app/api/http_ctrl.py"
    click Workflow "https://github.com/featurecloud/featurecloud/blob/master/FeatureCloud/workflow/workflow.py"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#004080
    classDef backend fill:#DFF2BF,stroke:#4F8A10
    classDef compute fill:#FFE4B5,stroke:#FF8C00
    classDef external fill:#F0F0F0,stroke:#666666
```
