# sahiansalome14/auto-scaling-controller architecture

> Architecture diagram of the GitHub repository sahiansalome14/auto-scaling-controller, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sahiansalome14/auto-scaling-controller
- Repository: https://github.com/sahiansalome14/auto-scaling-controller

## Overview

This repository’s product is a Go controller that continuously governs EC2 Auto Scaling capacity from CloudWatch and load-balancer signals. Its main workflow is observe, validate, decide, actuate, and record; a DynamoDB lease elects one active controller when leader election is enabled. The repository also supports k6-driven experiments and result analysis. Control-flow links follow the sampled controller code; experiment-analysis links reflect the documented workflow and visible load-generation utilities, not inspected orchestration internals.

Main entry points: [`cmd/controller/main.go`](https://github.com/sahiansalome14/auto-scaling-controller/blob/main/cmd/controller/main.go) (Controller loop), [`cmd/controller/aws.go`](https://github.com/sahiansalome14/auto-scaling-controller/blob/main/cmd/controller/aws.go) (AWS provider), [`loadgen/loadgen.js`](https://github.com/sahiansalome14/auto-scaling-controller/blob/main/loadgen/loadgen.js) (k6 load generator), [`cmd/controller/provider.go`](https://github.com/sahiansalome14/auto-scaling-controller/blob/main/cmd/controller/provider.go) (Cloud interface)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_control["Control loop"]
  node_main["Controller loop<br/>[main.go]"]
  node_config["Configuration<br/>[config.go]"]
  node_observe["Observation<br/>[observe.go]"]
  node_policy["Scaling policy<br/>[policy.go]"]
  node_provider["Cloud interface<br/>[provider.go]"]
  node_decisionlog["Decision log"]
  node_state["Persisted state"]
end

subgraph group_cloud["AWS integrations"]
  node_awsprovider["AWS provider<br/>[aws.go]"]
  node_cloudwatch["CloudWatch"]
  node_asg["Auto Scaling Group"]
  node_alb["Application Load Balancer"]
  node_instances["EC2 application instances"]
end

subgraph group_ha["High availability"]
  node_elector["Leader elector<br/>[leader.go]"]
  node_dynamodb[("DynamoDB lease table")]
end

subgraph group_experiments["Experiments and analysis"]
  node_loadgen["k6 load generator<br/>[loadgen.js]"]
  node_profiles["Load profiles"]
  node_converter["CSV converter<br/>[k6_to_csv.py]"]
  node_plotter["Result plotting<br/>[plot_results.py]"]
  node_results["Experiment results"]
end

node_operator(("Operator"))

node_operator -->|"configures and starts"| node_main
node_operator -->|"starts experiment"| node_loadgen
node_main -->|"loads settings"| node_config
node_main -->|"loads and saves"| node_state
node_main -.->|"checks leadership"| node_elector
node_elector -->|"acquires or renews lease"| node_dynamodb
node_main -->|"runs observation"| node_observe
node_observe -->|"fetches capacity and metrics"| node_provider
node_provider -->|"implemented by"| node_awsprovider
node_awsprovider -->|"queries metrics"| node_cloudwatch
node_awsprovider -->|"reads and sets capacity"| node_asg
node_awsprovider -->|"reads target health"| node_alb
node_asg -->|"manages capacity"| node_instances
node_alb -->|"routes traffic"| node_instances
node_main -->|"evaluates observation"| node_policy
node_main -->|"sets desired capacity"| node_provider
node_main -->|"appends cycle record"| node_decisionlog
node_loadgen -->|"uses stages from"| node_profiles
node_loadgen -->|"sends HTTP requests"| node_alb
node_loadgen -->|"produces raw CSV"| node_converter
node_converter -->|"writes load metrics"| node_results
node_decisionlog -->|"collected per run"| node_results
node_operator -->|"analyzes run"| node_plotter
node_plotter -->|"reads run data"| node_results

click node_main "https://github.com/sahiansalome14/auto-scaling-controller/blob/main/cmd/controller/main.go"
click node_config "https://github.com/sahiansalome14/auto-scaling-controller/blob/main/cmd/controller/config.go"
click node_observe "https://github.com/sahiansalome14/auto-scaling-controller/blob/main/cmd/controller/observe.go"
click node_policy "https://github.com/sahiansalome14/auto-scaling-controller/blob/main/cmd/controller/policy.go"
click node_provider "https://github.com/sahiansalome14/auto-scaling-controller/blob/main/cmd/controller/provider.go"
click node_awsprovider "https://github.com/sahiansalome14/auto-scaling-controller/blob/main/cmd/controller/aws.go"
click node_elector "https://github.com/sahiansalome14/auto-scaling-controller/blob/main/cmd/controller/leader.go"
click node_loadgen "https://github.com/sahiansalome14/auto-scaling-controller/blob/main/loadgen/loadgen.js"
click node_profiles "https://github.com/sahiansalome14/auto-scaling-controller/tree/main/loadgen/profiles"
click node_converter "https://github.com/sahiansalome14/auto-scaling-controller/blob/main/loadgen/k6_to_csv.py"
click node_plotter "https://github.com/sahiansalome14/auto-scaling-controller/blob/main/scripts/plot_results.py"
click node_results "https://github.com/sahiansalome14/auto-scaling-controller/tree/main/results"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main,node_config,node_observe,node_policy,node_provider,node_decisionlog,node_state toneBlue
class node_awsprovider,node_cloudwatch,node_asg,node_alb,node_instances toneAmber
class node_elector,node_dynamodb toneMint
class node_loadgen,node_profiles,node_converter,node_plotter,node_results toneRose
class node_operator toneIndigo
```

## Components

### Control loop

- [Controller loop](https://github.com/sahiansalome14/auto-scaling-controller/blob/main/cmd/controller/main.go): `cmd/controller/main.go`
- [Configuration](https://github.com/sahiansalome14/auto-scaling-controller/blob/main/cmd/controller/config.go): `cmd/controller/config.go`
- [Observation](https://github.com/sahiansalome14/auto-scaling-controller/blob/main/cmd/controller/observe.go): `cmd/controller/observe.go`
- [Scaling policy](https://github.com/sahiansalome14/auto-scaling-controller/blob/main/cmd/controller/policy.go): `cmd/controller/policy.go`
- [Cloud interface](https://github.com/sahiansalome14/auto-scaling-controller/blob/main/cmd/controller/provider.go): `cmd/controller/provider.go`
- **Decision log**
- **Persisted state**

### AWS integrations

- [AWS provider](https://github.com/sahiansalome14/auto-scaling-controller/blob/main/cmd/controller/aws.go): `cmd/controller/aws.go`
- **CloudWatch**
- **Auto Scaling Group**
- **Application Load Balancer**
- **EC2 application instances**

### High availability

- [Leader elector](https://github.com/sahiansalome14/auto-scaling-controller/blob/main/cmd/controller/leader.go): `cmd/controller/leader.go`
- **DynamoDB lease table**

### Experiments and analysis

- [k6 load generator](https://github.com/sahiansalome14/auto-scaling-controller/blob/main/loadgen/loadgen.js): `loadgen/loadgen.js`
- [Load profiles](https://github.com/sahiansalome14/auto-scaling-controller/tree/main/loadgen/profiles): `loadgen/profiles`
- [CSV converter](https://github.com/sahiansalome14/auto-scaling-controller/blob/main/loadgen/k6_to_csv.py): `loadgen/k6_to_csv.py`
- [Result plotting](https://github.com/sahiansalome14/auto-scaling-controller/blob/main/scripts/plot_results.py): `scripts/plot_results.py`
- [Experiment results](https://github.com/sahiansalome14/auto-scaling-controller/tree/main/results): `results`

### Other components

- **Operator**

## Connections

- Operator → Controller loop: configures and starts
- Operator → k6 load generator: starts experiment
- Controller loop → Configuration: loads settings
- Controller loop → Persisted state: loads and saves
- Controller loop → Leader elector: checks leadership
- Leader elector → DynamoDB lease table: acquires or renews lease
- Controller loop → Observation: runs observation
- Observation → Cloud interface: fetches capacity and metrics
- Cloud interface → AWS provider: implemented by
- AWS provider → CloudWatch: queries metrics
- AWS provider → Auto Scaling Group: reads and sets capacity
- AWS provider → Application Load Balancer: reads target health
- Auto Scaling Group → EC2 application instances: manages capacity
- Application Load Balancer → EC2 application instances: routes traffic
- Controller loop → Scaling policy: evaluates observation
- Controller loop → Cloud interface: sets desired capacity
- Controller loop → Decision log: appends cycle record
- k6 load generator → Load profiles: uses stages from
- k6 load generator → Application Load Balancer: sends HTTP requests
- k6 load generator → CSV converter: produces raw CSV
- CSV converter → Experiment results: writes load metrics
- Decision log → Experiment results: collected per run
- Operator → Result plotting: analyzes run
- Result plotting → Experiment results: reads run data