# azamalicodes/container-optimization-cybersecurity-platform architecture

> Architecture diagram of the GitHub repository azamalicodes/container-optimization-cybersecurity-platform, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/azamalicodes/container-optimization-cybersecurity-platform
- Repository: https://github.com/azamalicodes/container-optimization-cybersecurity-platform

## Overview

This repository optimizes and operates a cybersecurity learning platform that provisions isolated attacker–target container pairs, exposes session and benchmark APIs, and includes multi-host placement and monitoring. The principal workflow is learner → API → provisioning → Docker pair, with status and teardown through the API. Benchmark runs are also API-triggered. The README documents the main provisioning and benchmark relationships; the sampled agent and scheduler source establishes their interactions. Monitoring and some image details are represented from the tree and README, so their links are omitted where wiring was not shown.

Main entry points: [`orchestrator/api.js`](https://github.com/azamalicodes/container-optimization-cybersecurity-platform/blob/main/orchestrator/api.js) (Session API), [`orchestrator/provision.sh`](https://github.com/azamalicodes/container-optimization-cybersecurity-platform/blob/main/orchestrator/provision.sh) (Pair Provisioning), [`benchmark/measure-live.sh`](https://github.com/azamalicodes/container-optimization-cybersecurity-platform/blob/main/benchmark/measure-live.sh) (Live Measurement), [`orchestrator/host-agent.js`](https://github.com/azamalicodes/container-optimization-cybersecurity-platform/blob/main/orchestrator/host-agent.js) (Host Agent)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_session["Session Platform"]
  node_api["Session API<br/>[api.js]"]
  node_http["HTTP Shim<br/>[http_shim.js]"]
  node_provision["Pair Provisioning<br/>[provision.sh]"]
  node_labs["Lab Configs"]
  node_reaper["Idle Reaper<br/>[reaper.sh]"]
end

subgraph group_images["Container Images"]
  node_base["Shared Base Image"]
  node_target["Target Image"]
  node_bundles["Tool Bundles"]
end

subgraph group_measurement["Measurement"]
  node_benchmark_api["Benchmark API<br/>[api.js]"]
  node_measurement_run["Live Measurement<br/>[measure-live.sh]"]
  node_benchmark_model["Capacity Model<br/>[model.py]"]
end

subgraph group_scaling["Multi-host Scaling"]
  node_host_agent["Host Agent<br/>[host-agent.js]"]
  node_scheduler["Placement Scheduler<br/>[scheduler.js]"]
end

subgraph group_observability["Observability"]
  node_prometheus["Prometheus Config<br/>[prometheus.yml]"]
  node_alerts["Session Alerts<br/>[session-alerts.yml]"]
  node_grafana["Grafana Dashboard<br/>[sessions.json]"]
end

node_learner(("Learner / Client"))
node_docker["Docker Engine"]

node_learner -->|"requests sessions"| node_api
node_api -->|"uses router"| node_http
node_api -->|"starts provisioning"| node_provision
node_api -->|"inspects and removes"| node_docker
node_provision -->|"creates pair"| node_docker
node_provision -->|"reads lab settings"| node_labs
node_reaper -.->|"reaps idle sessions"| node_docker
node_docker -->|"runs images"| node_base
node_docker -->|"runs images"| node_target
node_docker -->|"runs images"| node_bundles
node_learner -->|"requests metrics"| node_benchmark_api
node_benchmark_api -->|"spawns measurement"| node_measurement_run
node_measurement_run -->|"measures containers"| node_docker
node_measurement_run -.->|"models capacity"| node_benchmark_model
node_host_agent -->|"registers and reports"| node_scheduler
node_host_agent -->|"provisions locally"| node_provision
node_prometheus -.->|"evaluates rules"| node_alerts
node_grafana -.->|"queries metrics"| node_prometheus

click node_api "https://github.com/azamalicodes/container-optimization-cybersecurity-platform/blob/main/orchestrator/api.js"
click node_http "https://github.com/azamalicodes/container-optimization-cybersecurity-platform/blob/main/orchestrator/lib/http_shim.js"
click node_provision "https://github.com/azamalicodes/container-optimization-cybersecurity-platform/blob/main/orchestrator/provision.sh"
click node_labs "https://github.com/azamalicodes/container-optimization-cybersecurity-platform/tree/main/lab-configs"
click node_reaper "https://github.com/azamalicodes/container-optimization-cybersecurity-platform/blob/main/orchestrator/reaper.sh"
click node_base "https://github.com/azamalicodes/container-optimization-cybersecurity-platform/blob/main/images/base/Dockerfile"
click node_target "https://github.com/azamalicodes/container-optimization-cybersecurity-platform/blob/main/images/target/Dockerfile"
click node_bundles "https://github.com/azamalicodes/container-optimization-cybersecurity-platform/tree/main/images/bundles"
click node_benchmark_api "https://github.com/azamalicodes/container-optimization-cybersecurity-platform/blob/main/orchestrator/api.js"
click node_measurement_run "https://github.com/azamalicodes/container-optimization-cybersecurity-platform/blob/main/benchmark/measure-live.sh"
click node_benchmark_model "https://github.com/azamalicodes/container-optimization-cybersecurity-platform/blob/main/benchmark/model.py"
click node_host_agent "https://github.com/azamalicodes/container-optimization-cybersecurity-platform/blob/main/orchestrator/host-agent.js"
click node_scheduler "https://github.com/azamalicodes/container-optimization-cybersecurity-platform/blob/main/orchestrator/scheduler.js"
click node_prometheus "https://github.com/azamalicodes/container-optimization-cybersecurity-platform/blob/main/monitoring/prometheus.yml"
click node_alerts "https://github.com/azamalicodes/container-optimization-cybersecurity-platform/blob/main/monitoring/rules/session-alerts.yml"
click node_grafana "https://github.com/azamalicodes/container-optimization-cybersecurity-platform/blob/main/monitoring/grafana/dashboards/sessions.json"

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_api,node_http,node_provision,node_labs,node_reaper,node_learner toneBlue
class node_base,node_target,node_bundles toneAmber
class node_benchmark_api,node_measurement_run,node_benchmark_model toneMint
class node_host_agent,node_scheduler toneRose
class node_prometheus,node_alerts,node_grafana,node_docker toneIndigo
```

## Components

### Session Platform

- [Session API](https://github.com/azamalicodes/container-optimization-cybersecurity-platform/blob/main/orchestrator/api.js): `orchestrator/api.js`
- [HTTP Shim](https://github.com/azamalicodes/container-optimization-cybersecurity-platform/blob/main/orchestrator/lib/http_shim.js): `orchestrator/lib/http_shim.js`
- [Pair Provisioning](https://github.com/azamalicodes/container-optimization-cybersecurity-platform/blob/main/orchestrator/provision.sh): `orchestrator/provision.sh`
- [Lab Configs](https://github.com/azamalicodes/container-optimization-cybersecurity-platform/tree/main/lab-configs): `lab-configs`
- [Idle Reaper](https://github.com/azamalicodes/container-optimization-cybersecurity-platform/blob/main/orchestrator/reaper.sh): `orchestrator/reaper.sh`

### Container Images

- [Shared Base Image](https://github.com/azamalicodes/container-optimization-cybersecurity-platform/blob/main/images/base/Dockerfile): `images/base/Dockerfile`
- [Target Image](https://github.com/azamalicodes/container-optimization-cybersecurity-platform/blob/main/images/target/Dockerfile): `images/target/Dockerfile`
- [Tool Bundles](https://github.com/azamalicodes/container-optimization-cybersecurity-platform/tree/main/images/bundles): `images/bundles`

### Measurement

- [Benchmark API](https://github.com/azamalicodes/container-optimization-cybersecurity-platform/blob/main/orchestrator/api.js): `orchestrator/api.js`
- [Live Measurement](https://github.com/azamalicodes/container-optimization-cybersecurity-platform/blob/main/benchmark/measure-live.sh): `benchmark/measure-live.sh`
- [Capacity Model](https://github.com/azamalicodes/container-optimization-cybersecurity-platform/blob/main/benchmark/model.py): `benchmark/model.py`

### Multi-host Scaling

- [Host Agent](https://github.com/azamalicodes/container-optimization-cybersecurity-platform/blob/main/orchestrator/host-agent.js): `orchestrator/host-agent.js`
- [Placement Scheduler](https://github.com/azamalicodes/container-optimization-cybersecurity-platform/blob/main/orchestrator/scheduler.js): `orchestrator/scheduler.js`

### Observability

- [Prometheus Config](https://github.com/azamalicodes/container-optimization-cybersecurity-platform/blob/main/monitoring/prometheus.yml): `monitoring/prometheus.yml`
- [Session Alerts](https://github.com/azamalicodes/container-optimization-cybersecurity-platform/blob/main/monitoring/rules/session-alerts.yml): `monitoring/rules/session-alerts.yml`
- [Grafana Dashboard](https://github.com/azamalicodes/container-optimization-cybersecurity-platform/blob/main/monitoring/grafana/dashboards/sessions.json): `monitoring/grafana/dashboards/sessions.json`

### Other components

- **Learner / Client**
- **Docker Engine**

## Connections

- Learner / Client → Session API: requests sessions (evidence: `README.md`)
- Session API → HTTP Shim: uses router (evidence: `orchestrator/api.js`)
- Session API → Pair Provisioning: starts provisioning (evidence: `README.md`)
- Session API → Docker Engine: inspects and removes (evidence: `orchestrator/api.js`)
- Pair Provisioning → Docker Engine: creates pair (evidence: `README.md`)
- Pair Provisioning → Lab Configs: reads lab settings (evidence: `README.md`)
- Idle Reaper → Docker Engine: reaps idle sessions
- Docker Engine → Shared Base Image: runs images (evidence: `README.md`)
- Docker Engine → Target Image: runs images (evidence: `README.md`)
- Docker Engine → Tool Bundles: runs images (evidence: `README.md`)
- Learner / Client → Benchmark API: requests metrics (evidence: `README.md`)
- Benchmark API → Live Measurement: spawns measurement (evidence: `README.md`)
- Live Measurement → Docker Engine: measures containers (evidence: `README.md`)
- Live Measurement → Capacity Model: models capacity
- Host Agent → Placement Scheduler: registers and reports (evidence: `orchestrator/host-agent.js`)
- Host Agent → Pair Provisioning: provisions locally (evidence: `orchestrator/host-agent.js`)
- Prometheus Config → Session Alerts: evaluates rules
- Grafana Dashboard → Prometheus Config: queries metrics