# aregm/icl architecture

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

- Interactive diagram: https://gitdiagram.com/aregm/icl
- Repository: https://github.com/aregm/icl

## Overview

ICL is a Python SDK for describing infrastructure, runtime dependencies, and programs through a unified API, then running workloads locally or on cloud infrastructure. The principal workflow is developer → define infrastructure/runtime/program → deploy and run → observe results and logs. Additional capabilities include Prefect flows, Docker image builds, cloud/infrastructure plugins, and JupyterHub-based development environments. The graph emphasizes relationships visible in excerpts or explicitly documented in the README; unsampled API and plugin behavior is represented conservatively.

Main entry points: [`src/infractl/docker/remote.py`](https://github.com/aregm/icl/blob/main/src/infractl/docker/remote.py) (Cluster Docker), [`src/infractl/plugins/prefect_runtime/runtime.py`](https://github.com/aregm/icl/blob/main/src/infractl/plugins/prefect_runtime/runtime.py) (Prefect Runtime), [`src/infractl/plugins/prefect_runtime/program.py`](https://github.com/aregm/icl/blob/main/src/infractl/plugins/prefect_runtime/program.py) (Prefect Program), [`src/infractl/api/program.py`](https://github.com/aregm/icl/blob/main/src/infractl/api/program.py) (Program API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Developer API"]
  node_api_infrastructure["Infrastructure API<br/>[infrastructure.py]"]
  node_api_program["Program API<br/>[program.py]"]
  node_api_runtime["Runtime API<br/>[runtime.py]"]
  node_api_deploy["Deploy API<br/>[deploy.py]"]
  node_api_run["Run API<br/>[run.py]"]
end

subgraph group_core["Execution Core"]
  node_infrastructure_model["Infrastructure Model<br/>[infrastructure.py]"]
  node_program_model["Program Model<br/>[program.py]"]
  node_runtime_model["Runtime Model<br/>[runtime.py]"]
  node_registry["Plugin Registry<br/>[registry.py]"]
  node_identity["Identity Utilities<br/>[identity.py]"]
  node_logging["Logging<br/>[logging.py]"]
end

subgraph group_adapters["Runtime Adapters"]
  node_docker_builder["Image Builder<br/>[builder.py]"]
  node_docker_local["Local Docker<br/>[local.py]"]
  node_docker_remote["Cluster Docker<br/>[remote.py]"]
  node_prefect_runtime["Prefect Runtime<br/>[runtime.py]"]
  node_prefect_program["Prefect Program<br/>[program.py]"]
  node_kubernetes_runtime["Kubernetes Runtime<br/>[runtime.py]"]
  node_aws_vpc["AWS Networking<br/>[vpc.py]"]
  node_icl_infrastructure["ICL Infrastructure<br/>[infrastructure.py]"]
  node_kubernetes_api["Kubernetes API<br/>[kubernetes.py]"]
end

subgraph group_environments["Development Environments"]
  node_jupyterhub["JupyterHub<br/>[jupyterhub.py]"]
  node_hub_config["Hub Configuration<br/>[config.py]"]
  node_hub_server["Hub Server<br/>[server.py]"]
end

node_developer(("Developer"))
node_prefect_service(("Prefect Service"))
node_cloud(("Cloud Infrastructure"))
node_workload["Python Workload"]

node_developer -->|"defines infrastructure"| node_api_infrastructure
node_developer -->|"defines program"| node_api_program
node_developer -->|"runs workload"| node_api_run
node_api_program -->|"creates"| node_program_model
node_api_infrastructure -->|"resolves"| node_infrastructure_model
node_api_runtime -.->|"configures"| node_runtime_model
node_api_deploy -.->|"deploys"| node_prefect_runtime
node_api_run -->|"executes"| node_workload
node_infrastructure_model -.->|"resolves plugins"| node_registry
node_docker_builder -->|"selects builder"| node_docker_local
node_docker_builder -->|"selects builder"| node_docker_remote
node_docker_remote -->|"deploys builder flow"| node_api_deploy
node_docker_remote -->|"creates builder program"| node_api_program
node_prefect_runtime -->|"deploys programs"| node_prefect_program
node_prefect_runtime -->|"uses orchestration"| node_prefect_service
node_prefect_program -->|"reads runs and logs"| node_prefect_service
node_kubernetes_runtime -.->|"uses Kubernetes"| node_kubernetes_api
node_icl_infrastructure -.->|"targets infrastructure"| node_cloud
node_aws_vpc -.->|"provides networking"| node_cloud
node_jupyterhub -->|"loads configuration"| node_hub_config
node_hub_server -.->|"serves hub"| node_jupyterhub
node_prefect_program -->|"sanitizes names"| node_identity

click node_api_infrastructure "https://github.com/aregm/icl/blob/main/src/infractl/api/infrastructure.py"
click node_api_program "https://github.com/aregm/icl/blob/main/src/infractl/api/program.py"
click node_api_runtime "https://github.com/aregm/icl/blob/main/src/infractl/api/runtime.py"
click node_api_deploy "https://github.com/aregm/icl/blob/main/src/infractl/api/deploy.py"
click node_api_run "https://github.com/aregm/icl/blob/main/src/infractl/api/run.py"
click node_infrastructure_model "https://github.com/aregm/icl/blob/main/src/infractl/base/infrastructure.py"
click node_program_model "https://github.com/aregm/icl/blob/main/src/infractl/base/program.py"
click node_runtime_model "https://github.com/aregm/icl/blob/main/src/infractl/base/runtime.py"
click node_registry "https://github.com/aregm/icl/blob/main/src/infractl/base/registry.py"
click node_docker_builder "https://github.com/aregm/icl/blob/main/src/infractl/docker/builder.py"
click node_docker_local "https://github.com/aregm/icl/blob/main/src/infractl/docker/local.py"
click node_docker_remote "https://github.com/aregm/icl/blob/main/src/infractl/docker/remote.py"
click node_prefect_runtime "https://github.com/aregm/icl/blob/main/src/infractl/plugins/prefect_runtime/runtime.py"
click node_prefect_program "https://github.com/aregm/icl/blob/main/src/infractl/plugins/prefect_runtime/program.py"
click node_kubernetes_runtime "https://github.com/aregm/icl/blob/main/src/infractl/plugins/kubernetes_runtime/runtime.py"
click node_aws_vpc "https://github.com/aregm/icl/blob/main/src/infractl/plugins/aws_infrastructure/vpc.py"
click node_icl_infrastructure "https://github.com/aregm/icl/blob/main/src/infractl/plugins/icl_infrastructure/infrastructure.py"
click node_kubernetes_api "https://github.com/aregm/icl/blob/main/src/infractl/kubernetes.py"
click node_jupyterhub "https://github.com/aregm/icl/blob/main/src/infractl/hub/jupyterhub.py"
click node_hub_config "https://github.com/aregm/icl/blob/main/src/infractl/hub/config.py"
click node_hub_server "https://github.com/aregm/icl/blob/main/src/infractl/hub/server.py"
click node_identity "https://github.com/aregm/icl/blob/main/src/infractl/identity.py"
click node_logging "https://github.com/aregm/icl/blob/main/src/infractl/logging.py"

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_infrastructure,node_api_program,node_api_runtime,node_api_deploy,node_api_run toneBlue
class node_infrastructure_model,node_program_model,node_runtime_model,node_registry,node_identity,node_logging toneAmber
class node_docker_builder,node_docker_local,node_docker_remote,node_prefect_runtime,node_prefect_program,node_kubernetes_runtime,node_aws_vpc,node_icl_infrastructure,node_kubernetes_api toneMint
class node_jupyterhub,node_hub_config,node_hub_server toneRose
class node_developer,node_prefect_service,node_cloud,node_workload toneIndigo
```

## Components

### Developer API

- [Infrastructure API](https://github.com/aregm/icl/blob/main/src/infractl/api/infrastructure.py): `src/infractl/api/infrastructure.py`
- [Program API](https://github.com/aregm/icl/blob/main/src/infractl/api/program.py): `src/infractl/api/program.py`
- [Runtime API](https://github.com/aregm/icl/blob/main/src/infractl/api/runtime.py): `src/infractl/api/runtime.py`
- [Deploy API](https://github.com/aregm/icl/blob/main/src/infractl/api/deploy.py): `src/infractl/api/deploy.py`
- [Run API](https://github.com/aregm/icl/blob/main/src/infractl/api/run.py): `src/infractl/api/run.py`

### Execution Core

- [Infrastructure Model](https://github.com/aregm/icl/blob/main/src/infractl/base/infrastructure.py): `src/infractl/base/infrastructure.py`
- [Program Model](https://github.com/aregm/icl/blob/main/src/infractl/base/program.py): `src/infractl/base/program.py`
- [Runtime Model](https://github.com/aregm/icl/blob/main/src/infractl/base/runtime.py): `src/infractl/base/runtime.py`
- [Plugin Registry](https://github.com/aregm/icl/blob/main/src/infractl/base/registry.py): `src/infractl/base/registry.py`
- [Identity Utilities](https://github.com/aregm/icl/blob/main/src/infractl/identity.py): `src/infractl/identity.py`
- [Logging](https://github.com/aregm/icl/blob/main/src/infractl/logging.py): `src/infractl/logging.py`

### Runtime Adapters

- [Image Builder](https://github.com/aregm/icl/blob/main/src/infractl/docker/builder.py): `src/infractl/docker/builder.py`
- [Local Docker](https://github.com/aregm/icl/blob/main/src/infractl/docker/local.py): `src/infractl/docker/local.py`
- [Cluster Docker](https://github.com/aregm/icl/blob/main/src/infractl/docker/remote.py): `src/infractl/docker/remote.py`
- [Prefect Runtime](https://github.com/aregm/icl/blob/main/src/infractl/plugins/prefect_runtime/runtime.py): `src/infractl/plugins/prefect_runtime/runtime.py`
- [Prefect Program](https://github.com/aregm/icl/blob/main/src/infractl/plugins/prefect_runtime/program.py): `src/infractl/plugins/prefect_runtime/program.py`
- [Kubernetes Runtime](https://github.com/aregm/icl/blob/main/src/infractl/plugins/kubernetes_runtime/runtime.py): `src/infractl/plugins/kubernetes_runtime/runtime.py`
- [AWS Networking](https://github.com/aregm/icl/blob/main/src/infractl/plugins/aws_infrastructure/vpc.py): `src/infractl/plugins/aws_infrastructure/vpc.py`
- [ICL Infrastructure](https://github.com/aregm/icl/blob/main/src/infractl/plugins/icl_infrastructure/infrastructure.py): `src/infractl/plugins/icl_infrastructure/infrastructure.py`
- [Kubernetes API](https://github.com/aregm/icl/blob/main/src/infractl/kubernetes.py): `src/infractl/kubernetes.py`

### Development Environments

- [JupyterHub](https://github.com/aregm/icl/blob/main/src/infractl/hub/jupyterhub.py): `src/infractl/hub/jupyterhub.py`
- [Hub Configuration](https://github.com/aregm/icl/blob/main/src/infractl/hub/config.py): `src/infractl/hub/config.py`
- [Hub Server](https://github.com/aregm/icl/blob/main/src/infractl/hub/server.py): `src/infractl/hub/server.py`

### Other components

- **Developer**
- **Prefect Service**
- **Cloud Infrastructure**
- **Python Workload**

## Connections

- Developer → Infrastructure API: defines infrastructure
- Developer → Program API: defines program
- Developer → Run API: runs workload
- Program API → Program Model: creates (evidence: `src/infractl/api/program.py`)
- Infrastructure API → Infrastructure Model: resolves (evidence: `src/infractl/api/infrastructure.py`)
- Runtime API → Runtime Model: configures
- Deploy API → Prefect Runtime: deploys
- Run API → Python Workload: executes
- Infrastructure Model → Plugin Registry: resolves plugins
- Image Builder → Local Docker: selects builder (evidence: `src/infractl/docker/builder.py`)
- Image Builder → Cluster Docker: selects builder (evidence: `src/infractl/docker/builder.py`)
- Cluster Docker → Deploy API: deploys builder flow (evidence: `src/infractl/docker/remote.py`)
- Cluster Docker → Program API: creates builder program (evidence: `src/infractl/docker/remote.py`)
- Prefect Runtime → Prefect Program: deploys programs (evidence: `src/infractl/plugins/prefect_runtime/runtime.py`)
- Prefect Runtime → Prefect Service: uses orchestration (evidence: `src/infractl/plugins/prefect_runtime/runtime.py`)
- Prefect Program → Prefect Service: reads runs and logs (evidence: `src/infractl/plugins/prefect_runtime/program.py`)
- Kubernetes Runtime → Kubernetes API: uses Kubernetes
- ICL Infrastructure → Cloud Infrastructure: targets infrastructure
- AWS Networking → Cloud Infrastructure: provides networking
- JupyterHub → Hub Configuration: loads configuration (evidence: `src/infractl/hub/jupyterhub.py`)
- Hub Server → JupyterHub: serves hub
- Prefect Program → Identity Utilities: sanitizes names (evidence: `src/infractl/plugins/prefect_runtime/program.py`)
