# edgerun/faas-sim architecture

> Architecture diagram of the GitHub repository edgerun/faas-sim, 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/edgerun/faas-sim
- Repository: https://github.com/edgerun/faas-sim

## Overview

##### Project type and purpose
- faas-sim is an open-source, trace-driven Function-as-a-Service (FaaS) simulation framework written in Python.
- It lets researchers and engineers model container-based serverless platforms, swap in custom scheduling, autoscaling, and load-balancing strategies, and collect detailed metrics on system behavior.

##### File structure
- Top‐level packaging:
- setup.py, requirements*.txt
- sim/ (core simulation engine)
- ext/raith21/ (optional Raith21 plugin modules: generators, resource monitors, oracles, function sims)
- examples/ (CLI‐driven usage examples)
- notebooks/ (Jupyter notebooks for interactive analysis)
- doc/ (Sphinx docs, high‐level architecture figure)
- sim/faas: implements the FaaS layer (function execution, scaling, watchdogs).
- sim/core: wraps SimPy, drives event loop, collects metrics, logs.
- sim/oracle: “ground truth” predictors and data generators for function durations.
- sim/net, sim/docker, sim/resource, sim/topology: model network, container runtime, hardware resources, and cluster topology via Ether.

##### README for additional insights
- High-level architecture:
- SimPy (discrete-event core)
- Ether (network simulation & topology builder)
- Skippy (default scheduler)
- Trace & profiling-data ingestion
- Plug-in points for scheduler/autoscaler/load-balancer

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interface Layer
    subgraph "User Interface"
        direction TB
        CLI["CLI Examples"]:::ui
        NB["Jupyter Notebooks"]:::ui
    end

    %% Simulation Engine Layer
    subgraph "Simulation Engine"
        direction TB
        Entry["Entry Point (faassim.py)"]:::core
        CoreLoop["Event Loop (SimPy)"]:::core
        Benchmark["Benchmark Harness"]:::core
        RequestGen["Request Generator"]:::core
        HPA["HPA Shim"]:::core
        Metrics["Metrics Collection"]:::core
        Logging["Logging Subsystem"]:::core
    end

    %% FaaS Layer
    subgraph "FaaS Layer"
        direction TB
        SystemCtrl["System Controller"]:::faas
        Scaling["Scaling & Autoscaling"]:::faas
        Watchdogs["Watchdogs & Monitors"]:::faas
        Skippy["Default Scheduler (Skippy)"]:::faas
    end

    %% Infrastructure Layer
    subgraph "Infrastructure Model"
        direction TB
        Network["Network Model (Ether)"]:::infra
        Docker["Container Runtime Model"]:::infra
        Resource["Hardware Resource Model"]:::infra
        Topology["Cluster Topology Builder"]:::infra
    end

    %% Oracle Services
    subgraph "Oracle & Data"
        direction TB
        OracleIface["Oracle Interface"]:::data
        DistData["Data Distributions"]:::data
    end

    %% Plugin Extensions
    subgraph "Raith21 Plugins"
        direction TB
        RaithCore["Raith21 Core"]:::plugin
        DeviceMod["Device Models"]:::plugin
        TopoDef["Topology Definitions"]:::plugin
        ResMonExt["Resource Monitor Ext"]:::plugin
        FuncSimExt["FunctionSim Ext"]:::plugin
        OracleImpl["Oracle Implementations"]:::plugin
        GenPlugins["Scheduler & Generator Plugins"]:::plugin
    end

    %% Documentation & Examples
    subgraph "Documentation & Examples"
        direction TB
        DataExamples["Trace & Profile Data Examples"]:::data
        Docs["Architecture Docs"]:::data
    end

    %% Data Flows
    CLI -->|"runs simulation"| Entry
    NB -->|"runs analysis"| Entry
    Entry -->|"initializes"| CoreLoop
    Entry -->|"loads config"| RequestGen
    RequestGen --> CoreLoop
    CoreLoop -->|"dispatches invocations"| SystemCtrl
    SystemCtrl -->|"uses"| Skippy
    SystemCtrl -->|"allocates containers"| Docker
    Docker -->|"updates usage"| Resource
    Resource -->|"topology info"| SystemCtrl
    SystemCtrl -->|"monitored by"| Watchdogs
    Watchdogs -->|"feedback"| Scaling
    Scaling --> Skippy
    CoreLoop -->|"collects metrics"| Metrics
    CoreLoop -->|"logs events"| Logging
    Metrics -->|"outputs"| DataExamples
    Metrics -->|"documents"| Docs
    CoreLoop -->|"queries durations"| OracleIface
    OracleIface --> DistData
    OracleIface --> OracleImpl
    SystemCtrl --> GenPlugins
    Resource --> RaithCore
    RaithCore --> DeviceMod
    RaithCore --> TopoDef
    RaithCore --> ResMonExt
    RaithCore --> FuncSimExt
    RaithCore --> OracleImpl
    RaithCore --> GenPlugins

    %% Click Events
    click CLI "https://github.com/edgerun/faas-sim/blob/master/examples/basic/main.py"
    click NB "https://github.com/edgerun/faas-sim/blob/master/notebooks/workload_patterns.ipynb"
    click Entry "https://github.com/edgerun/faas-sim/blob/master/sim/faassim.py"
    click CoreLoop "https://github.com/edgerun/faas-sim/blob/master/sim/core.py"
    click Benchmark "https://github.com/edgerun/faas-sim/blob/master/sim/benchmark.py"
    click RequestGen "https://github.com/edgerun/faas-sim/blob/master/sim/requestgen.py"
    click HPA "https://github.com/edgerun/faas-sim/blob/master/sim/hpa.py"
    click Metrics "https://github.com/edgerun/faas-sim/blob/master/sim/metrics.py"
    click Logging "https://github.com/edgerun/faas-sim/blob/master/sim/logging.py"
    click SystemCtrl "https://github.com/edgerun/faas-sim/blob/master/sim/faas/system.py"
    click Scaling "https://github.com/edgerun/faas-sim/blob/master/sim/faas/scaling.py"
    click Watchdogs "https://github.com/edgerun/faas-sim/blob/master/sim/faas/watchdogs.py"
    click Skippy "https://github.com/edgerun/faas-sim/blob/master/sim/skippy.py"
    click OracleIface "https://github.com/edgerun/faas-sim/blob/master/sim/oracle/oracle.py"
    click DistData "https://github.com/edgerun/faas-sim/blob/master/sim/oracle/data/distributions.py"
    click Network "https://github.com/edgerun/faas-sim/blob/master/sim/net.py"
    click Docker "https://github.com/edgerun/faas-sim/blob/master/sim/docker.py"
    click Resource "https://github.com/edgerun/faas-sim/blob/master/sim/resource.py"
    click Topology "https://github.com/edgerun/faas-sim/blob/master/sim/topology.py"
    click RaithCore "https://github.com/edgerun/faas-sim/tree/master/ext/raith21/"
    click DeviceMod "https://github.com/edgerun/faas-sim/blob/master/ext/raith21/device.py"
    click TopoDef "https://github.com/edgerun/faas-sim/blob/master/ext/raith21/topology.py"
    click ResMonExt "https://github.com/edgerun/faas-sim/blob/master/ext/raith21/resourcemonitor.py"
    click FuncSimExt "https://github.com/edgerun/faas-sim/blob/master/ext/raith21/functionsim.py"
    click OracleImpl "https://github.com/edgerun/faas-sim/blob/master/ext/raith21/oracles.py"
    click GenPlugins "https://github.com/edgerun/faas-sim/tree/master/ext/raith21/generators/"
    click DataExamples "https://github.com/edgerun/faas-sim/tree/master/doc/examples/"
    click Docs "https://github.com/edgerun/faas-sim/blob/master/doc/system/index.rst"

    %% Styles
    classDef ui fill:#D0E6F8,stroke:#0366D6,stroke-width:1px
    classDef core fill:#BDD7EE,stroke:#1155CC,stroke-width:1px
    classDef faas fill:#D5E8D4,stroke:#107C10,stroke-width:1px
    classDef infra fill:#FDE9D9,stroke:#B45309,stroke-width:1px
    classDef plugin stroke-dasharray: 5 5,stroke:#905,fill:none
    classDef data fill:#F2F2F2,stroke:#666,stroke-width:1px,shape:cylinder
```
