# samuelmarti22/controllerasg architecture

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

## Overview

ControllerASG is a self-managed EC2 autoscaling controller. Its main workflow loads validated configuration, periodically reads managed fleet state, observes CloudWatch metrics, applies safety and threshold rules, performs EC2/Target Group changes, and records one auditable decision per tick. The README documents additional operational capabilities; the sampled source confirms the core runtime wiring and scaling actions, but not every behavior such as signal handling details beyond main or the validation-only mode.

Main entry points: [`controller/controller.go`](https://github.com/samuelmarti22/controllerasg/blob/main/controller/controller.go) (Cycle and policy), [`provisioner/provisioner.go`](https://github.com/samuelmarti22/controllerasg/blob/main/provisioner/provisioner.go) (Fleet and actuator), [`main/main.go`](https://github.com/samuelmarti22/controllerasg/blob/main/main/main.go) (Runtime entry), [`observer/observer.go`](https://github.com/samuelmarti22/controllerasg/blob/main/observer/observer.go) (Metric observer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Control loop"]
  node_main["Runtime entry<br/>[main.go]"]
  node_controller["Cycle and policy<br/>[controller.go]"]
end

subgraph group_cloud["AWS integration"]
  node_observer["Metric observer<br/>[observer.go]"]
  node_provisioner["Fleet and actuator<br/>[provisioner.go]"]
end

subgraph group_audit["Decision audit"]
  node_decisionlog["JSONL logger<br/>[logger.go]"]
end

subgraph group_domain["Domain and config"]
  node_config["Config loader<br/>[configuration.go]"]
  node_decisionrecord["Decision record<br/>[decision.go]"]
  node_instance["Fleet instance<br/>[instances.go]"]
  node_metric["Observed metric<br/>[metrics.go]"]
end

node_operator(("Operator"))
node_cloudwatch["CloudWatch"]
node_ec2["EC2"]
node_elb["ELB Target Group"]
node_configfile["Configuration file"]
node_logfile[("Decision log")]

node_operator -->|"starts"| node_main
node_main -->|"loads and validates"| node_config
node_configfile -->|"provides settings"| node_config
node_main -->|"ticks periodically"| node_controller
node_main -->|"constructs"| node_observer
node_main -->|"constructs"| node_provisioner
node_main -->|"constructs"| node_decisionlog
node_controller -->|"reads fleet"| node_provisioner
node_provisioner -->|"describes instances"| node_ec2
node_provisioner -->|"reads target health"| node_elb
node_controller -->|"requests metrics"| node_observer
node_observer -->|"queries metrics"| node_cloudwatch
node_observer -->|"returns aggregates"| node_metric
node_controller -->|"supplies fleet"| node_instance
node_controller -->|"scales fleet"| node_provisioner
node_provisioner -->|"launches or terminates"| node_ec2
node_provisioner -->|"registers or drains"| node_elb
node_controller -->|"builds cycle record"| node_decisionrecord
node_controller -->|"logs each tick"| node_decisionlog
node_decisionlog -->|"writes JSONL"| node_logfile

click node_main "https://github.com/samuelmarti22/controllerasg/blob/main/main/main.go"
click node_config "https://github.com/samuelmarti22/controllerasg/blob/main/configuration/configuration.go"
click node_controller "https://github.com/samuelmarti22/controllerasg/blob/main/controller/controller.go"
click node_observer "https://github.com/samuelmarti22/controllerasg/blob/main/observer/observer.go"
click node_provisioner "https://github.com/samuelmarti22/controllerasg/blob/main/provisioner/provisioner.go"
click node_decisionlog "https://github.com/samuelmarti22/controllerasg/blob/main/logger/logger.go"
click node_decisionrecord "https://github.com/samuelmarti22/controllerasg/blob/main/model/decision.go"
click node_instance "https://github.com/samuelmarti22/controllerasg/blob/main/model/instances.go"
click node_metric "https://github.com/samuelmarti22/controllerasg/blob/main/model/metrics.go"

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_controller toneBlue
class node_observer,node_provisioner,node_logfile toneAmber
class node_decisionlog toneMint
class node_config,node_decisionrecord,node_instance,node_metric toneRose
class node_operator,node_cloudwatch,node_ec2,node_elb,node_configfile toneIndigo
```

## Components

### Control loop

- [Runtime entry](https://github.com/samuelmarti22/controllerasg/blob/main/main/main.go): `main/main.go`
- [Cycle and policy](https://github.com/samuelmarti22/controllerasg/blob/main/controller/controller.go): `controller/controller.go`

### AWS integration

- [Metric observer](https://github.com/samuelmarti22/controllerasg/blob/main/observer/observer.go): `observer/observer.go`
- [Fleet and actuator](https://github.com/samuelmarti22/controllerasg/blob/main/provisioner/provisioner.go): `provisioner/provisioner.go`

### Decision audit

- [JSONL logger](https://github.com/samuelmarti22/controllerasg/blob/main/logger/logger.go): `logger/logger.go`

### Domain and config

- [Config loader](https://github.com/samuelmarti22/controllerasg/blob/main/configuration/configuration.go): `configuration/configuration.go`
- [Decision record](https://github.com/samuelmarti22/controllerasg/blob/main/model/decision.go): `model/decision.go`
- [Fleet instance](https://github.com/samuelmarti22/controllerasg/blob/main/model/instances.go): `model/instances.go`
- [Observed metric](https://github.com/samuelmarti22/controllerasg/blob/main/model/metrics.go): `model/metrics.go`

### Other components

- **Operator**
- **CloudWatch**
- **EC2**
- **ELB Target Group**
- **Configuration file**
- **Decision log**

## Connections

- Operator → Runtime entry: starts
- Runtime entry → Config loader: loads and validates
- Configuration file → Config loader: provides settings
- Runtime entry → Cycle and policy: ticks periodically
- Runtime entry → Metric observer: constructs
- Runtime entry → Fleet and actuator: constructs
- Runtime entry → JSONL logger: constructs
- Cycle and policy → Fleet and actuator: reads fleet
- Fleet and actuator → EC2: describes instances
- Fleet and actuator → ELB Target Group: reads target health
- Cycle and policy → Metric observer: requests metrics
- Metric observer → CloudWatch: queries metrics
- Metric observer → Observed metric: returns aggregates
- Cycle and policy → Fleet instance: supplies fleet
- Cycle and policy → Fleet and actuator: scales fleet
- Fleet and actuator → EC2: launches or terminates
- Fleet and actuator → ELB Target Group: registers or drains
- Cycle and policy → Decision record: builds cycle record
- Cycle and policy → JSONL logger: logs each tick
- JSONL logger → Decision log: writes JSONL