# m4hf0d/faas-dave architecture

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

- Interactive diagram: https://gitdiagram.com/m4hf0d/faas-dave
- Repository: https://github.com/m4hf0d/faas-dave

## Overview

##### Project Type and Purpose
- faas-sim is an open-source, trace-driven simulation framework written in Python.
- Its goal is to model and evaluate container-based Function-as-a-Service (FaaS) platforms using discrete-event simulation (SimPy) and a network layer (Ether).
- Users can plug in custom schedulers, autoscalers, load-balancers, and request generators.

##### File Structure Analysis
- Top‐level directories:
- sim: core simulation engine, context definitions, platform abstractions, FaaS system modules, utilities
- ext/raith21: extensions for ML-driven scheduling, device models, workload generators
- examples: runnable scenarios demonstrating custom schedulers, load-balancers, function simulators
- notebooks: Jupyter notebooks for explorations and plotting
- doc: Sphinx documentation and architecture overviews
- Key architectural patterns:
- Factory pattern in sim/context to create platform services (deployment, network, node, replica, request, telemetry, trace, zone)
- Plugin architecture in sim/faas for scheduling, scaling, load balancing, watchdogs
- Separation of concerns between simulation core (SimPy engine) and platform models/services

##### Extracting Architecture Details from README
- Core technologies: SimPy (discrete events), Ether (network simulation), Skippy (default scheduler)
- Trace-driven: uses profiling data and workload traces for function execution times
- Pluggable components: schedulers, autoscalers, load-balancers

##### Main Components
a. Input Layer
- Workload Traces & Profiling Data (fed into Request Generator)
- Configuration Files (cluster topology, device profiles)
b. Request Generator
- sim/requestgen.py and custom request generators in examples/request_gen
c. Simulation Core
- sim/core.py: orchestrates SimPy environment
- sim/docker.py: container setup for function execution
- sim/net.py: integrates Ether network events
d. Context Factories & Models
- sim/context/*: factory modules instantiate platform components
- Each platform aspect = service + model (deployment, network, node, replica, request, telemetry, trace, zone)
e. FaaS System Modules
- sim/faas/core.py: glue between simulation and FaaS abstractions
- sim/faas/decentralized.py, scaling.py, loadbalancers.py, watchdogs.py, kvstorage.py, system.py
- ext/raith21/*: optional ML-based scheduling, generative models
f. Measurement & Analysis
- sim/metrics.py: collects and computes performance metrics
- sim/logging.py: event logging
- sim/oracle: ground truth services (for evaluation)
g. Output & Visualization
- CLI reports, logs, and notebook interfaces (notebooks/)

##### Relationships and Data Flows
- Simulation Core ↔ Context Services (network events, deployment, node lifecycle, telemetry)
- Simulation Core ↔ FaaS System Modules (scheduling decisions, autoscaling triggers, load balancing)
- FaaS System Modules → Resource Model (sim/resource.py) → Execution in containers (sim/docker.py)
- Telemetry & Tracing Services report back to Metrics & Oracle for analysis

##### Architectural Patterns & Design Principles
- Discrete Event Simulation (SimPy) drives all events
- Factory pattern for modular platform component instantiation
- Plugin architecture allows swapping scheduling/scaling/LB implementations
- Clear separation: Core engine vs. platform services vs. FaaS logic vs. extensions

##### Detail Level
- Plugin interfaces in sim/faas to show where users drop in custom code

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Input Layer
    subgraph "Input Layer"
        WT["Workload Traces & Profiling Data"]:::input
        CF["Configuration Files"]:::input
    end

    %% Request Generator
    subgraph "Request Generator"
        RG["Request Generator"]:::core
        ERG["Example Request Generators"]:::example
    end

    %% Simulation Core
    subgraph "Simulation Core"
        SC["Event Engine"]:::core
        NI["Network Integration"]:::core
        CE["Container Execution"]:::core
    end

    %% Platform Services
    subgraph "Platform Services"
        CFAC["Context Factory"]:::core
        subgraph "Deployment"
            Dfac["Deployment Factory"]
            Dmod["Deployment Model"]
            Dsvc["Deployment Service"]
        end
        subgraph "Network"
            Nfac["Network Factory"]
            Nsvc["Network Service"]
        end
        subgraph "Node"
            NOfac["Node Factory"]
            NOmod["Node Model"]
        end
        subgraph "Replica"
            Rfac["Replica Factory"]
            Rmod["Replica Model"]
            Rsvc["Replica Service"]
        end
        subgraph "Request"
            Reqfac["Request Factory"]
            Reqsvc["Request Service"]
        end
        subgraph "Telemetry"
            Tlfac["Telemetry Factory"]
            Tlsvc["Telemetry Service"]
        end
        subgraph "Trace"
            Trfac["Trace Factory"]
            Trsvc["Trace Service"]
        end
        subgraph "Zone"
            Zfac["Zone Factory"]
        end
    end

    %% FaaS Logic
    subgraph "FaaS Logic"
        FCore["FaaS Core Glue"]:::faas
        FDec["Decentralized Scheduling"]:::faas
        FScale["Autoscaling"]:::faas
        FLB["Load Balancers"]:::faas
        FWD["Watchdogs"]:::faas
        FKV["KV Storage"]:::faas
        FSY["System Composition"]:::faas
        DS["Default Scheduler (Skippy)"]:::external
    end

    %% Extensions
    subgraph "Extensions"
        EXT["ML-Driven Scheduling & Models"]:::ext
    end

    %% Measurement & Analysis
    subgraph "Measurement & Analysis"
        MET["Metrics Collection"]:::core
        LOG["Event Logging"]:::core
        ORA["Ground-Truth Oracle"]:::core
    end

    %% Resource & Runner
    subgraph "Resource & Runner"
        RM["Resource Model"]:::core
        RUN["Top-Level Runner"]:::core
    end

    %% Examples & Notebooks
    subgraph "Examples & Notebooks"
        EX["Examples"]:::example
        NB["Notebooks"]:::example
    end

    %% External Dependencies
    subgraph "External Dependencies"
        SIMPY["SimPy"]:::external
        ETHER["Ether"]:::external
    end

    %% Connections
    WT --> RG
    CF --> RG
    ERG --> RG
    RG --> SC
    SC --> NI
    SC --> CE
    SC --> CFAC
    SC --> FCore
    FCore --> FDec
    FCore --> FScale
    FCore --> FLB
    FCore --> FWD
    FCore --> FKV
    FCore --> FSY
    FCore --> SC
    FDec --> DS
    CFAC --> Dfac
    CFAC --> Nfac
    CFAC --> NOfac
    CFAC --> Rfac
    CFAC --> Reqfac
    CFAC --> Tlfac
    CFAC --> Trfac
    CFAC --> Zfac
    Dfac --> SC
    Nfac --> NI
    NOfac --> SC
    Rfac --> CE
    Reqfac --> SC
    Tlsvc --> MET
    Trsvc --> ORA
    SC --> RM
    RM --> CE
    CE --> LOG
    MET --> ORA
    EXT --> FDec
    EX --> FCore
    NB --> MET
    SIMPY -.-> SC
    ETHER -.-> NI

    %% Click Events
    click WT "https://github.com/m4hf0d/faas-dave/blob/main/sim/oracle/data/distributions.py"
    click CF "https://github.com/m4hf0d/faas-dave/blob/main/sim/topology.py"
    click RG "https://github.com/m4hf0d/faas-dave/blob/main/sim/requestgen.py"
    click ERG "https://github.com/m4hf0d/faas-dave/blob/main/examples/request_gen/main.py"
    click SC "https://github.com/m4hf0d/faas-dave/blob/main/sim/core.py"
    click NI "https://github.com/m4hf0d/faas-dave/blob/main/sim/net.py"
    click CE "https://github.com/m4hf0d/faas-dave/blob/main/sim/docker.py"
    click CFAC "https://github.com/m4hf0d/faas-dave/blob/main/sim/context/factory.py"
    click Dfac "https://github.com/m4hf0d/faas-dave/blob/main/sim/context/platform/deployment/factory.py"
    click Dmod "https://github.com/m4hf0d/faas-dave/blob/main/sim/context/platform/deployment/model.py"
    click Dsvc "https://github.com/m4hf0d/faas-dave/blob/main/sim/context/platform/deployment/service.py"
    click Nfac "https://github.com/m4hf0d/faas-dave/blob/main/sim/context/platform/network/factory.py"
    click Nsvc "https://github.com/m4hf0d/faas-dave/blob/main/sim/context/platform/network/service.py"
    click NOfac "https://github.com/m4hf0d/faas-dave/blob/main/sim/context/platform/node/factory.py"
    click NOmod "https://github.com/m4hf0d/faas-dave/blob/main/sim/context/platform/node/model.py"
    click Rfac "https://github.com/m4hf0d/faas-dave/blob/main/sim/context/platform/replica/factory.py"
    click Rmod "https://github.com/m4hf0d/faas-dave/blob/main/sim/context/platform/replica/model.py"
    click Rsvc "https://github.com/m4hf0d/faas-dave/blob/main/sim/context/platform/replica/service.py"
    click Reqfac "https://github.com/m4hf0d/faas-dave/blob/main/sim/context/platform/request/factory.py"
    click Reqsvc "https://github.com/m4hf0d/faas-dave/blob/main/sim/context/platform/request/service.py"
    click Tlfac "https://github.com/m4hf0d/faas-dave/blob/main/sim/context/platform/telemetry/factory.py"
    click Tlsvc "https://github.com/m4hf0d/faas-dave/blob/main/sim/context/platform/telemetry/service.py"
    click Trfac "https://github.com/m4hf0d/faas-dave/blob/main/sim/context/platform/trace/factory.py"
    click Trsvc "https://github.com/m4hf0d/faas-dave/blob/main/sim/context/platform/trace/service.py"
    click Zfac "https://github.com/m4hf0d/faas-dave/blob/main/sim/context/platform/zone/factory.py"
    click FCore "https://github.com/m4hf0d/faas-dave/blob/main/sim/faas/core.py"
    click FDec "https://github.com/m4hf0d/faas-dave/blob/main/sim/faas/decentralized.py"
    click FScale "https://github.com/m4hf0d/faas-dave/blob/main/sim/faas/scaling.py"
    click FLB "https://github.com/m4hf0d/faas-dave/blob/main/sim/faas/loadbalancers.py"
    click FWD "https://github.com/m4hf0d/faas-dave/blob/main/sim/faas/watchdogs.py"
    click FKV "https://github.com/m4hf0d/faas-dave/blob/main/sim/faas/kvstorage.py"
    click FSY "https://github.com/m4hf0d/faas-dave/blob/main/sim/faas/system.py"
    click EXT "https://github.com/m4hf0d/faas-dave/tree/main/ext/raith21/"
    click MET "https://github.com/m4hf0d/faas-dave/blob/main/sim/metrics.py"
    click LOG "https://github.com/m4hf0d/faas-dave/blob/main/sim/logging.py"
    click ORA "https://github.com/m4hf0d/faas-dave/blob/main/sim/oracle/oracle.py"
    click RM "https://github.com/m4hf0d/faas-dave/blob/main/sim/resource.py"
    click DS "https://github.com/m4hf0d/faas-dave/blob/main/sim/skippy.py"
    click RUN "https://github.com/m4hf0d/faas-dave/blob/main/sim/faassim.py"
    click EX "https://github.com/m4hf0d/faas-dave/tree/main/examples/"
    click NB "https://github.com/m4hf0d/faas-dave/tree/main/notebooks/"

    %% Styles
    classDef core fill:#E0F7FA,stroke:#006064,color:#006064
    classDef faas fill:#E8F5E9,stroke:#2E7D32,color:#2E7D32
    classDef ext fill:#FFF3E0,stroke:#EF6C00,color:#EF6C00
    classDef external fill:#ECEFF1,stroke:#455A64,color:#455A64
    classDef example fill:#F3E5F5,stroke:#6A1B9A,color:#6A1B9A
    classDef input fill:#E1F5FE,stroke:#0277BD,color:#0277BD
```
