# yelp/paasta architecture

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

- Interactive diagram: https://gitdiagram.com/yelp/paasta
- Repository: https://github.com/yelp/paasta

## Overview

##### Project type and purpose
- PaaSTA is an opinionated Platform‐as‐a‐Service toolkit written in Python. It provides:
- A command‐line interface (paasta CLI) for teams to build, deploy, and manage containerized services.
- A REST API (“paasta API server”) to expose operational data and control endpoints.
- A library of automation primitives (paasta_tools) that orchestrates interactions with Kubernetes, Mesos (legacy), SmartStack/Envoy, Sensu, Prometheus/HPA, Tron, and other infrastructure.
- Its goal is to take high‐level, declarative service definitions and ensure safe, efficient deployments across Kubernetes clusters, integrate service discovery, monitoring, autoscaling, and batch scheduling.

##### File structure
- Top‐level directories:
- paasta_tools/cli – the entry point for the paasta command, subcommands, schemas, and tab‐completion scripts.
- paasta_tools/api & paasta_tools/paastaapi – the implementation of the HTTP API server (routes, views, models, client).
- paasta_tools – core automation library: autoscaling, kubernetes tools, mesos tools, config loaders, utility scripts.
- docs/ + docs/source – user & developer documentation source (Sphinx).
- example_cluster/ – example Kubernetes/Mesos cluster configurations and test scripts.
- general_itests/ & k8s_itests/ – integration tests that spin up fake clusters or Kind.
- yelp_package/dockerfiles & itest – Dockerfiles and integration test infrastructure for building and packaging.
- Config files and CI:
- .github/workflows – CI pipelines (run tests, publish to PyPI).
- Docker‐related: Dockerfiles for various components, docker‐compose for example clusters.
- Makefile, setup.py, pyproject.toml, requirements*.txt – build, packaging, and dependency management.

##### README for additional insights
- PaaSTA binds to Kubernetes for scheduling, Docker for containers, Tron for cron‐style jobs, SmartStack/Envoy for service discovery, Sensu for monitoring, Prometheus/HPA for autoscaling, and optional Jenkins for CD.
- It uses declarative service schemas (JSON/YAML) and generates Kubernetes manifests plus other infra configs.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Developer Tier
    subgraph "Developer Tier"
        Dev("Developers"):::user
        Dev -->|"invokes CLI"| CLI
        Dev -->|"queries API"| API
    end

    %% PaaSTA Core
    subgraph "PaaSTA Core"
        CLI["paasta CLI"]:::cli
        API["paasta API Server"]:::api
        APIClient["paasta API Client"]:::apiClient

        subgraph "Automation Library (paasta_tools)"
            CoreLib["Core Automation Library"]:::library
            K8sInt["Kubernetes Integration"]:::library
            MesosInt["Mesos Integration"]:::library
            SmartStack["SmartStack Tools"]:::library
            Envoy["Envoy Tools"]:::library
            Sensu["Sensu Adapters"]:::library
            Prometheus["Prometheus Adapter"]:::library
            Autoscale["Autoscaling Controllers"]:::library
            TronMod["Batch Scheduler (Tron)"]:::library
            ConfigLoader["Declarative Config Loader"]:::library
        end
    end

    %% External Infrastructure
    subgraph "External Infrastructure"
        K8S["Kubernetes API"]:::infra
        REG["Docker Registry"]:::infra
        SDMesh["Service Discovery Mesh"]:::infra
        Monitoring["Monitoring & Alerting Platform"]:::infra
        Autoscalers["Node Pool Autoscalers"]:::infra
        TRON["Tron Scheduler Service"]:::infra
        GIT["Git Config Repository"]:::infra
        CI_CD["Jenkins (CD)"]:::infra
    end

    %% Control & Data Flows
    CLI -->|"uses library"| CoreLib
    CLI -->|"deploy, update"| K8S
    CLI -->|"push/pull images"| REG
    CLI -->|"configure SD"| SDMesh
    CLI -->|"setup monitoring"| Monitoring
    CLI -->|"schedule jobs"| TRON

    API -->|"serves JSON"| Dev
    API -->|"uses library"| CoreLib
    APIClient -->|"calls API"| API

    CoreLib -->|"orchestrates"| K8sInt
    CoreLib -->|"orchestrates"| MesosInt
    CoreLib -->|"orchestrates"| SmartStack
    CoreLib -->|"orchestrates"| Envoy
    CoreLib -->|"orchestrates"| Sensu
    CoreLib -->|"orchestrates"| Prometheus
    CoreLib -->|"orchestrates"| Autoscale
    CoreLib -->|"orchestrates"| TronMod
    CoreLib -->|"loads configs"| ConfigLoader

    K8sInt -->|"calls Kubernetes API"| K8S
    MesosInt -->|"calls Mesos"| K8S
    SmartStack -->|"configures mesh"| SDMesh
    Envoy -->|"configures proxy"| SDMesh
    Sensu -->|"sends alerts"| Monitoring
    Prometheus -->|"collects metrics"| Monitoring
    Autoscale -->|"drives HPA/VPA"| Monitoring
    Autoscale -->|"scales nodes"| Autoscalers
    TronMod -->|"schedules cron jobs"| TRON
    ConfigLoader -->|"reads schemas"| GIT

    %% Click Events
    click CLI "https://github.com/yelp/paasta/tree/master/paasta_tools/cli"
    click API "https://github.com/yelp/paasta/tree/master/paasta_tools/api"
    click APIClient "https://github.com/yelp/paasta/tree/master/paasta_tools/paastaapi"
    click CoreLib "https://github.com/yelp/paasta/tree/master/paasta_tools/"
    click K8sInt "https://github.com/yelp/paasta/tree/master/paasta_tools/kubernetes"
    click MesosInt "https://github.com/yelp/paasta/tree/master/paasta_tools/mesos"
    click SmartStack "https://github.com/yelp/paasta/blob/master/paasta_tools/smartstack_tools.py"
    click Envoy "https://github.com/yelp/paasta/blob/master/paasta_tools/envoy_tools.py"
    click Sensu "https://github.com/yelp/paasta/blob/master/paasta_tools/monitoring_tools.py"
    click Prometheus "https://github.com/yelp/paasta/blob/master/paasta_tools/setup_prometheus_adapter_config.py"
    click Autoscale "https://github.com/yelp/paasta/tree/master/paasta_tools/autoscaling"
    click TronMod "https://github.com/yelp/paasta/tree/master/paasta_tools/tron"
    click ConfigLoader "https://github.com/yelp/paasta/blob/master/paasta_tools/paasta_service_config_loader.py"

    %% Styles
    classDef user fill:#ffcccc,stroke:#b30000,color:#000;
    classDef cli fill:#ccffcc,stroke:#009900,color:#000;
    classDef api fill:#ccccff,stroke:#0000b3,color:#000;
    classDef apiClient fill:#e0ccff,stroke:#8000b3,color:#000;
    classDef library fill:#c2e0ff,stroke:#004080,color:#000;
    classDef infra fill:#f0f0f0,stroke:#666666,color:#000;
```
