# kuzmik/proxysql-agent architecture

> Architecture diagram of the GitHub repository kuzmik/proxysql-agent, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2024-12-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kuzmik/proxysql-agent
- Repository: https://github.com/kuzmik/proxysql-agent

## Overview

##### Main Components

a) Core Components:
- ProxySQL Agent (Central Component)
- ProxySQL Core Pods
- ProxySQL Satellite Pods
- Kubernetes Integration Points
- HTTP API Server
- Configuration Management

b) External Dependencies:
- MySQL Backend Servers
- Kubernetes API Server
- ProxySQL Admin Interface

**┌─ Kubernetes Cluster ──────────────────────────────┐**
- ┌─ ProxySQL Core Deployment ─┐ ┌─ Satellite ─┐  │
- ┌─ Pod ─────────────┐     │ │  Deployment │  │
- ProxySQL        │     │ │   (Similar  │  │
- ProxySQL Agent  │     │ │  structure) │  │
- ┘     │ └────────────┘   │
- ┘                  │
- ┘

**┌─ ProxySQL Agent ───────────────────────┐**
- ┌─ Configuration ─┐ ┌─ ProxySQL Core ─┐│
- YAML Config  │ │  - Admin API    ││
- ENV Vars     │ │  - Monitoring   ││
- ┘ └────────────────┘ │
- ┌─ REST API ──────┐ ┌─ Health Check ─┐│
- /health      │ │  - Liveness    ││
- /shutdown    │ │  - Readiness   ││
- ┘ └────────────────┘ │
- ┘

##### Key Elements to Highlight

- Blue: Kubernetes components
- Green: ProxySQL components
- Yellow: Agent components
- Gray: External services

b) Connection Types:

##### Specific Implementation Details

- The agent's connection to ProxySQL admin interface (127.0.0.1:6032)
- Kubernetes service discovery for core/satellite communication
- HTTP API endpoints for health checks and shutdown
- Configuration flow from core to satellite nodes

##### Important Workflows

- Satellite pod scaling workflow
- Core pod recycling process
- Shutdown sequence
- Health check flow

##### Technical Specifications

- Go version requirements
- Key dependencies (k8s-client-go, slog, Viper)
- Configuration options
- Port mappings

##### Notes for Implementation

- Maintain consistent spacing and alignment
- Version information
- Notes for critical points (e.g., "Self-healing cluster management")
- Document failure scenarios and recovery paths

Remember to keep the focus on the agent's role in maintaining the ProxySQL cluster state, especially in the context of Kubernetes pod scaling and lifecycle management.

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph Kubernetes["Kubernetes Cluster"]
        subgraph CoreDeployment["ProxySQL Core Deployment"]
            CorePod["Core Pod"]
            subgraph CoreComponents["Core Components"]
                Agent["ProxySQL Agent"]:::agent
                ProxySQLCore["ProxySQL Core Service"]:::proxysql
                Config["Configuration Management"]:::config
                API["HTTP API Server"]:::api
            end
        end

        subgraph SatelliteDeployment["ProxySQL Satellite Deployment"]
            SatPod["Satellite Pod"]
            subgraph SatComponents["Satellite Components"]
                SatAgent["Satellite Agent"]:::agent
                ProxySQLSat["ProxySQL Satellite Service"]:::proxysql
            end
        end

        K8sAPI["Kubernetes API Server"]:::k8s
    end

    subgraph External["External Components"]
        MySQL["MySQL Backend Servers"]:::db
    end

    subgraph Components["Component Details"]
        ConfigFiles["Configuration Files"]:::files
        BuildSystem["Build System"]:::build
        CICD["CI/CD Workflows"]:::cicd
    end

    %% Relationships
    Agent --> ProxySQLCore
    Agent --> K8sAPI
    ProxySQLCore --> MySQL
    SatAgent --> ProxySQLSat
    ProxySQLSat --> MySQL
    Agent --> SatAgent
    Config --> Agent
    API --> Agent
    ConfigFiles --> Config
    
    %% Click Events
    click Agent "https://github.com/kuzmik/proxysql-agent/blob/main/cmd/proxysql-agent/main.go"
    click Config "https://github.com/kuzmik/proxysql-agent/blob/main/internal/configuration/configuration.go"
    click ConfigFiles "https://github.com/kuzmik/proxysql-agent/tree/main/configs"
    click ProxySQLCore "https://github.com/kuzmik/proxysql-agent/blob/main/internal/proxysql/core.go"
    click ProxySQLSat "https://github.com/kuzmik/proxysql-agent/blob/main/internal/proxysql/satellite.go"
    click API "https://github.com/kuzmik/proxysql-agent/blob/main/internal/restapi/restapi.go"
    click BuildSystem "https://github.com/kuzmik/proxysql-agent/tree/main/build"
    click CICD "https://github.com/kuzmik/proxysql-agent/tree/main/.github/workflows"

    %% Styling
    classDef agent fill:#FFE873,stroke:#333,stroke-width:2px
    classDef proxysql fill:#90EE90,stroke:#333,stroke-width:2px
    classDef k8s fill:#326CE5,stroke:#333,stroke-width:2px,color:#FFF
    classDef config fill:#F8F8F8,stroke:#333,stroke-width:2px
    classDef api fill:#FFA07A,stroke:#333,stroke-width:2px
    classDef db fill:#B8D4FF,stroke:#333,stroke-width:2px
    classDef files fill:#E8E8E8,stroke:#333,stroke-width:2px
    classDef build fill:#D3D3D3,stroke:#333,stroke-width:2px
    classDef cicd fill:#FFB6C1,stroke:#333,stroke-width:2px

    %% Legend
    subgraph Legend
        L1["ProxySQL Agent"]:::agent
        L2["ProxySQL Service"]:::proxysql
        L3["Kubernetes Component"]:::k8s
        L4["Configuration"]:::config
        L5["API Service"]:::api
        L6["Database"]:::db
        L7["Files"]:::files
        L8["Build"]:::build
        L9["CI/CD"]:::cicd
    end
```
