# cloudforet-io/supervisor architecture

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

- Interactive diagram: https://gitdiagram.com/cloudforet-io/supervisor
- Repository: https://github.com/cloudforet-io/supervisor

## Overview

##### Project type and purpose
- This is a standalone Python-based “Supervisor Service” whose purpose is to dynamically deploy and manage plugin collectors (e.g., aws-ec2, google-oauth2) either as Docker containers or Kubernetes pods.  It exposes a gRPC interface so that an external inventory service can request plugin endpoints, and Supervisor will deploy the plugin on demand if it’s not already running.

##### File structure
- Top-level:
- Dockerfile, .dockerignore, skaffold.template.yaml, deploy/helm/… → container/K8s deployment artifacts
- src/spaceone/supervisor/… → Python application code, organized in subpackages:
– interface/grpc → gRPC server definitions
– service → high-level RPC service implementations
– manager → orchestrator logic that decides what to deploy and when
– scheduler → scheduling logic for sync and health checks
– connector → low-level drivers (Docker API, Kubernetes API, plugin repository, generic container connector)
– conf → global and scheduler configuration
– error, info → structured error and telemetry data
- pkg/pip_requirements.txt & setup.py → Python packaging
- .github/workflows → CI/CD pipelines, automated chart builds and releases

##### README for additional insights
- Describes two operating modes (Docker vs. K8s) and that the service is deployed standalone.

##### Elements
- Blue for internal application layers (Interface, Service, Manager, Scheduler)
- Green for connectors
- Orange for external systems (Docker, K8s)
- Gray for configuration

[Client] → [gRPC Interface] → [SupervisorService] → [PluginServiceManager] → [SyncScheduler] → {DockerConnector → Docker Daemon | K8sConnector → K8s API} → [Plugin Runtime]

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Consumer
    Client["Inventory Service (Client)"]:::external

    %% Interface Layer
    subgraph "Interface Layer"
        GRPC["gRPC Interface"]:::interface
    end

    %% Service Layer
    subgraph "Service Layer"
        SupService["SupervisorService"]:::service
    end

    %% Manager Layer
    subgraph "Manager Layer"
        PluginMgr["PluginServiceManager"]:::manager
        SupMgr["SupervisorManager"]:::manager
        RepoConn["Repository Connector"]:::connector
    end

    %% Scheduler Layer
    subgraph "Scheduler Layer"
        Scheduler["SyncScheduler"]:::scheduler
    end

    %% Connector Layer
    subgraph "Connector Layer"
        DockerConn["Docker Connector"]:::connector
        K8sConn["Kubernetes Connector"]:::connector
        GenericConn["Generic Container Connector"]:::connector
        PluginConn["Plugin Connector"]:::connector
    end

    %% External Systems
    subgraph "External Systems"
        DockerDaemon["Docker Daemon"]:::external
        K8sAPI["Kubernetes API Server"]:::external
    end

    %% Configuration
    subgraph "Configuration"
        GlobalConf["global_conf.py"]:::config
        SchedConf["scheduler_conf.py"]:::config
    end

    %% Connections
    Client -->|"GetEndpoint"| GRPC
    GRPC -->|"dispatch request"| SupService
    SupService -->|"check status"| PluginMgr
    SupService -->|"orchestrate"| SupMgr
    PluginMgr -->|"fetch metadata"| RepoConn
    SupMgr -->|"schedule retry or health checks"| Scheduler
    Scheduler -->|"deploy via"| DockerConn
    Scheduler -->|"deploy via"| K8sConn
    DockerConn -->|"create container"| DockerDaemon
    K8sConn -->|"create pod"| K8sAPI
    DockerConn -->|"use generic runtime"| GenericConn
    K8sConn -->|"use generic runtime"| GenericConn
    GenericConn -->|"invoke plugin driver"| PluginConn
    PluginConn -->|"return endpoint"| SupService
    SupService -->|"respond with endpoint"| GRPC
    GRPC -->|"return response"| Client

    %% Click Events
    click GRPC "https://github.com/cloudforet-io/supervisor/tree/master/src/spaceone/supervisor/interface/grpc"
    click SupService "https://github.com/cloudforet-io/supervisor/blob/master/src/spaceone/supervisor/service/supervisor_service.py"
    click PluginMgr "https://github.com/cloudforet-io/supervisor/blob/master/src/spaceone/supervisor/manager/plugin_service_manager.py"
    click SupMgr "https://github.com/cloudforet-io/supervisor/blob/master/src/spaceone/supervisor/manager/supervisor_manager.py"
    click Scheduler "https://github.com/cloudforet-io/supervisor/blob/master/src/spaceone/supervisor/scheduler/sync_scheduler.py"
    click RepoConn "https://github.com/cloudforet-io/supervisor/blob/master/src/spaceone/supervisor/connector/repository_connector.py"
    click DockerConn "https://github.com/cloudforet-io/supervisor/blob/master/src/spaceone/supervisor/connector/docker_connector.py"
    click K8sConn "https://github.com/cloudforet-io/supervisor/blob/master/src/spaceone/supervisor/connector/kubernetes_connector.py"
    click GenericConn "https://github.com/cloudforet-io/supervisor/blob/master/src/spaceone/supervisor/connector/container_connector.py"
    click PluginConn "https://github.com/cloudforet-io/supervisor/blob/master/src/spaceone/supervisor/connector/plugin_connector.py"
    click GlobalConf "https://github.com/cloudforet-io/supervisor/blob/master/src/spaceone/supervisor/conf/global_conf.py"
    click SchedConf "https://github.com/cloudforet-io/supervisor/blob/master/src/spaceone/supervisor/conf/scheduler_conf.py"
    click DockerDaemon "https://github.com/cloudforet-io/supervisor/tree/master/Dockerfile"
    click K8sAPI "https://github.com/cloudforet-io/supervisor/tree/master/deploy/helm"

    %% Styles
    classDef interface fill:#cce5ff,stroke:#3399ff,color:#333;
    classDef service fill:#cce5ff,stroke:#3399ff,color:#333;
    classDef manager fill:#cce5ff,stroke:#3399ff,color:#333;
    classDef scheduler fill:#cce5ff,stroke:#3399ff,color:#333;
    classDef connector fill:#d4edda,stroke:#28a745,color:#333;
    classDef external fill:#ffe5b4,stroke:#ff9900,color:#333;
    classDef config fill:#e2e3e5,stroke:#6c757d,color:#333;
```
