# Architecture

## CRD Relationships

```mermaid
graph TD
  CachedImage -->|references| PullPolicy
  CachedImageSet -->|references| PullPolicy
  CachedImageSet -->|references| DiscoveryPolicy
```

## Package Dependencies

```mermaid
graph LR
  cmd/main.go --> internal/controller
  internal/controller --> api/v1alpha1
  internal/controller --> internal/discovery
  internal/controller --> internal/metrics
  internal/controller --> internal/pacing
  internal/controller --> internal/podbuilder
  internal/pacing --> api/v1alpha1
  internal/pacing --> internal/podbuilder
  internal/podbuilder --> api/v1alpha1
```

## Reconciler → CRD Mapping

| CRD | Controller | Dependencies |
|-----|-----------|--------------|
| CachedImage | `internal/controller/cachedimage_controller.go` | podbuilder, pacing, metrics |
| CachedImageSet | `internal/controller/cachedimageset_controller.go` | podbuilder, pacing, metrics |
| DiscoveryPolicy | `internal/controller/discoverypolicy_controller.go` | podbuilder, pacing, metrics |
| PullPolicy | (config-only) |  |

## Pull Mechanism

```mermaid
sequenceDiagram
  participant CR as CachedImage
  participant Ctrl as Controller
  participant Pace as Pacing Engine
  participant K8s as Kubernetes API
  participant Node as Kubelet

  CR->>Ctrl: Reconcile triggered
  Ctrl->>Pace: Request pull slot
  Pace-->>Ctrl: Slot granted
  Ctrl->>K8s: Create Pod (nodeName=target)
  K8s->>Node: Schedule Pod
  Node->>Node: Pull image (kubelet)
  Node-->>K8s: Pod succeeds
  K8s-->>Ctrl: Watch event
  Ctrl->>CR: Update status (Ready)
```