# ailabstw/flavor architecture

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

- Interactive diagram: https://gitdiagram.com/ailabstw/flavor
- Repository: https://github.com/ailabstw/flavor

## Overview

##### Project Overview & Purpose
- The project is a Federated Learning and Validation Framework that enables multiple parties to collaboratively build and evaluate AI models while maintaining data privacy.
- It supports not only federated training (with both client and server examples) but also model validation and inference services. It’s designed to integrate with user-provided training code (even if not in Python) by invoking it as a subprocess.
- The README shows distinct sections and examples focused on FL clients (using various ML libraries like PyTorch, Tensorflow, SVM, XGBoost), FL servers, validation (FV), and model inference.

##### Analyzing the File Structure & Components
- Top-Level Example Directories:
- “examples/fl-client”: Contains several subdirectories (pytorch, svm, tensorflow, xgboost) that showcase how a federated learning client can be implemented with different frameworks.
- “examples/fl-server”: Provides an example of a federated learning server, including Dockerfiles and a README.
- “examples/fv”: Focuses on Federated Validation.
- “examples/inference”: Contains notebooks, Dockerfiles, and documentation that explain how to deploy inference models.
- Core Package (flavor directory):
- “flavor/cli”: Implements command-line utilities and checkers (e.g., for FL, FV, and aggregated FL tasks).
- “flavor/cook” and “flavor/taste”: Likely handle model “cooking” (preparing models) and possibly evaluation or further orchestration.
- “flavor/serve”: Contains the inference and serving logic. It is well segmented into:
∙ “inference” submodule with data models (both API and functional), inference models (including base classes for different inference strategies, such as Triton), and strategies (like AICoCO and Gradio).
∙ “invocations”: Handling the process by which code is invoked for inference.
- “flavor/gadget”: Contains specific integrations (for example, an xgboost module).
- Supporting Files:
- Dockerfiles in example directories indicate that containerized execution is a factor, meaning the system design should highlight container boundaries and how FLaVor interacts with external training/inference environments.
- Configuration and linting files (.flake8, .gitignore, .pre-commit-config.yaml, pyproject.toml) indicate a well-standardized project setup.

a. Main Components to Include:
- Federated Learning Client: Show components handling multiple frameworks (PyTorch, TensorFlow, SVM, XGBoost) with Docker-contained examples that run user training code.
- Federated Learning Server: Central orchestration service to coordinate client interactions, model aggregation, and communications.
- Federated Validation Component: Illustrate how validation jobs are set up (referencing the FV example) and interact with training and inference components.
- Inference Service: Represented by the “flavor/serve” module (with nested inference data models, inference models, strategies, and invocation mechanisms).
- Command-line/Utility Layer: Represent the CLI tools available under “flavor/cli” which act as entry points for various operations (checking, aggregating, serving, etc.).
- Auxiliary Components: “flavor/cook” and “flavor/taste” function as processing or preparation layers before deployment or during model assembly.

b. Relationships and Interactions:
- That the FL Server may trigger subprocesses to run user code within isolated Docker containers.
- That the CLI layer interacts with both the server and local modules (cooking/tasting) to facilitate workflow management.
- For inference, illustrate data flow from user requests (or from aggregated training outputs) to the “flavor/serve” subsystem which then leverages specific inference strategies (e.g., Triton, Gradio).

c. Key Architectural Patterns and Principles:
- Modularization: The project is divided into specialized modules (client, server, validation, inference) for separation of concerns.
- Containerization: Use of Docker in examples points to encapsulating user code execution to prevent environment conflicts.
- Extensibility: Through a well-structured CLI and plugin-like modules (in “cook”, “taste”, and “gadget”), the architecture promotes easy extensions—especially for integrating non-Python code.
- Subprocess Isolation: The design’s emphasis on calling external code using subprocess indicates a safeguard against dependency conflicts.

d. Technologies & Frameworks:
- The examples indicate popular ML frameworks (PyTorch, TensorFlow, SVM libraries, XGBoost).
- Docker for containerization.
- REST/HTTP (and legacy gRPC) for communication (as noted in changelog regarding Inference service and FL via HTTP).
- Use of Python’s packaging and CLI tools (as indicated by pyproject.toml, flavor/cli).

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Federated Learning Clients"
        fclient["Federated Learning Client"]:::client
        pclient["PyTorch Client"]:::client
        svclient["SVM Client"]:::client
        tclient["TensorFlow Client"]:::client
        xclient["XGBoost Client"]:::client
    end

    subgraph "Federated Learning Orchestration"
        fserver["Federated Learning Server"]:::server
        cli["CLI/Utility Layer (flavor/cli)"]:::cli
        cook["Model Preparation (Cooking)"]:::module
        taste["Additional Processing (Tasting)"]:::module
    end

    subgraph "Validation & Inference"
        fv["Federated Validation"]:::validation
        inferenceCore["Inference Core Engine"]:::inference
        inferenceInvoke["Inference Invocation Mechanism"]:::inference
        inferenceExample["Inference Service Examples"]:::inference
        gadget["Specific Integrations (XGBoost)"]:::integration
    end

    cli -->|"commands"| fserver
    fserver -->|"communicates"| fclient
    fserver -->|"communicates"| pclient
    fserver -->|"communicates"| svclient
    fserver -->|"communicates"| tclient
    fserver -->|"communicates"| xclient

    cli -->|"initiates"| cook
    cli -->|"initiates"| taste

    fserver -->|"sends_output"| inferenceCore
    inferenceCore -->|"uses"| inferenceInvoke
    inferenceInvoke -->|"triggers"| inferenceExample
    inferenceCore -->|"integrates"| gadget

    fserver -->|"validation_trigger"| fv
    fv -->|"feedback"| fserver

    click fclient "https://github.com/ailabstw/flavor/tree/main/examples/fl-client"
    click pclient "https://github.com/ailabstw/flavor/tree/main/examples/fl-client/pytorch"
    click svclient "https://github.com/ailabstw/flavor/tree/main/examples/fl-client/svm"
    click tclient "https://github.com/ailabstw/flavor/tree/main/examples/fl-client/tensorflow"
    click xclient "https://github.com/ailabstw/flavor/tree/main/examples/fl-client/xgboost"
    click fserver "https://github.com/ailabstw/flavor/tree/main/examples/fl-server"
    click fv "https://github.com/ailabstw/flavor/tree/main/examples/fv"
    click inferenceExample "https://github.com/ailabstw/flavor/tree/main/examples/inference"
    click inferenceCore "https://github.com/ailabstw/flavor/tree/main/flavor/serve/inference"
    click inferenceInvoke "https://github.com/ailabstw/flavor/blob/main/flavor/serve/invocations/infer_invocation.py"
    click cli "https://github.com/ailabstw/flavor/tree/main/flavor/cli"
    click cook "https://github.com/ailabstw/flavor/tree/main/flavor/cook"
    click taste "https://github.com/ailabstw/flavor/tree/main/flavor/taste"
    click gadget "https://github.com/ailabstw/flavor/blob/main/flavor/gadget/xgboost.py"

    classDef client fill:#f9c,stroke:#333,stroke-width:2px;
    classDef server fill:#bbf,stroke:#333,stroke-width:2px;
    classDef cli fill:#9f9,stroke:#333,stroke-width:2px;
    classDef module fill:#ff9,stroke:#333,stroke-width:2px;
    classDef validation fill:#fc9,stroke:#333,stroke-width:2px;
    classDef inference fill:#cff,stroke:#333,stroke-width:2px;
    classDef integration fill:#c9f,stroke:#333,stroke-width:2px;
```
