# t1mt/spegel architecture

> Architecture diagram of the GitHub repository t1mt/spegel, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/t1mt/spegel
- Repository: https://github.com/t1mt/spegel

## Overview

##### Project Type and Purpose
- Spegel is a specialized tool designed to cache images locally within a cluster environment. Its primary purpose is to reduce external dependencies (for example, Docker Hub outages or rate limiting), improve image pull speeds, and lower egress traffic.
- The project is written in Go and aimed at deployment in Kubernetes clusters, as evidenced by the Helm charts and Kubernetes-specific internal components.

##### Main Architectural Components
- External Services:
- External OCI Registries: The sources of container images that Spegel caches.
- End-users (cluster nodes, kubelets, or internal API clients) requesting image pulls.
- Spegel Service (Main Application):
- Entry Point: The main.go file, initializing the application.
- HTTP API / Router: The internal/mux package handles requests and responses.
- Routing Module: The pkg/routing (with subcomponents like p2p and bootstrap) which likely governs how requests are directed, perhaps implementing local load-balancing or peer-to-peer communication within the cluster.
- Core Business Logic and Data Handling:
- OCI Operations: The pkg/oci package manages container image operations (pulling, caching, and possible integration with containerd) along with associated test data.
- Registry Handling: The pkg/registry module, which likely implements the distribution API protocols.
- State Management: The pkg/state package for maintaining the status of cached images or any in-memory/in-cluster state.
- Metrics: The pkg/metrics package for collecting observations and performance counters.
- Auxiliary Internal Packages: The internal/buffer and internal/channel packages, which may be used to handle asynchronous processes or data pipelining in a concurrent environment.
- Kubernetes Integration:
- The internal/kubernetes package suggests that the application interacts with Kubernetes-specific APIs or resources.
- Deployment and Configuration:
- Helm Charts: The charts/spegel directory indicates the project’s packaging for Kubernetes.
- Dockerfiles (Dockerfile and Dockerfile.dev) imply containerization, which is critical in deployment environments.

##### Relationships and Interactions
- Incoming image requests from within the cluster are routed through the HTTP API (internal/mux), which directs the request to the appropriate module (routing, state management).
- The OCI module handles pulling the image from an external OCI registry if it is not already present in the local cache.
- The registry module then serves the image back to the requesting client in compliance with distribution protocols.
- Metrics are collected throughout the process, exposing operational insights.
- Auxiliary channels/buffers may be used internally to manage asynchronous data flows (for example, between request handling and image caching).
- The Kubernetes module might be used for self-monitoring and dynamic configuration adjustments within the cluster.
- Helm charts define how these components are deployed and configured in the cluster.

##### Architectural Patterns
- Layered Service Architecture: Separation of concerns is clearly visible in distinct packages (e.g., mux for HTTP routing, oci for container image logic, registry for distribution capabilities).
- Modular Design: Independent modules (metrics, state, routing) aid in maintenance and extensibility.
- Statelessness: As noted in the README, the core design is stateless, meaning no persistent internal state is maintained outside the cluster session, which simplifies scaling and deployment at the cost of external dependencies for persistence if needed.
- Containerized Microservice Deployment: Dockerfiles and Helm charts support the containerization and orchestration principles used in modern cloud-native applications.

##### Detailed Step-by-Step Approach
3. Branch out to show how requests are processed:
- One branch goes to the OCI module, responsible for pulling and caching images.
- Another branch possibly handles registry distribution via the registry module.
4. Underlying support modules:
- Detail state management for caching decisions.
- How metrics are integrated to monitor performance.
- Background processing channels using the buffer and channel modules.
5. Finally, at the side or bottom, incorporate Kubernetes integration—how Spegel is deployed and orchestrated—with Helm charts and corresponding Docker container processes.

## Diagram (Mermaid)

```mermaid
graph TD
    %% External Interaction Layer
    subgraph "External Interaction"
        EX1["External OCI Registries"]:::external
        EX2["Cluster Clients"]:::external
    end

    %% Spegel Service (Main Application)
    subgraph "Spegel Service"
        S1["Entry Point"]:::service
        S2["HTTP API/Router"]:::service
    end

    %% Business Logic Modules
    subgraph "Business Logic Modules"
        BL1["Routing Module"]:::module
        BL2["OCI Operations"]:::module
        BL3["Registry Module"]:::module
        BL4["State Management"]:::module
    end

    %% Auxiliary Modules
    subgraph "Auxiliary Modules"
        AU1["Metrics Collection"]:::auxiliary
        AU2["Buffer"]:::auxiliary
        AU3["Channel"]:::auxiliary
    end

    %% Kubernetes Integration
    subgraph "Kubernetes Integration"
        K1["Kubernetes Integration"]:::k8s
    end

    %% Deployment & Containerization
    subgraph "Deployment & Containerization"
        D1["Helm Charts"]:::deployment
        D2["Dockerfile"]:::deployment
        D3["Dockerfile.dev"]:::deployment
    end

    %% External interactions to API
    EX1 -->|"pulls image"| S2
    EX2 -->|"requests image"| S2

    %% Spegel Service interactions
    S1 -->|"bootstraps"| S2

    %% API routing to business logic modules
    S2 -->|"routes to"| BL1
    S2 -->|"calls"| BL2
    S2 -->|"calls"| BL3
    S2 -->|"updates"| BL4

    %% Business logic interactions with auxiliary modules
    BL2 -->|"metrics"| AU1
    BL3 -->|"metrics"| AU1
    BL4 -->|"metrics"| AU1

    %% Asynchronous processing flows
    BL1 -->|"async"| AU2
    BL1 -->|"async"| AU3

    %% Business logic integration with Kubernetes
    BL4 -->|"k8s events"| K1

    %% Deployment connections
    S1 -->|"deployed by"| D1
    D1 -->|"container based on"| D2
    D1 -->|"container based on"| D3

    %% Click Events
    click S1 "https://github.com/t1mt/spegel/blob/dev-0.0.30/main.go"
    click S2 "https://github.com/t1mt/spegel/blob/dev-0.0.30/internal/mux/mux.go"
    click BL1 "https://github.com/t1mt/spegel/blob/dev-0.0.30/pkg/routing/bootstrap.go"
    click BL2 "https://github.com/t1mt/spegel/blob/dev-0.0.30/pkg/oci/oci.go"
    click BL3 "https://github.com/t1mt/spegel/blob/dev-0.0.30/pkg/registry/registry.go"
    click BL4 "https://github.com/t1mt/spegel/blob/dev-0.0.30/pkg/state/state.go"
    click AU1 "https://github.com/t1mt/spegel/blob/dev-0.0.30/pkg/metrics/metrics.go"
    click AU2 "https://github.com/t1mt/spegel/blob/dev-0.0.30/internal/buffer/buffer.go"
    click AU3 "https://github.com/t1mt/spegel/blob/dev-0.0.30/internal/channel/channel.go"
    click K1 "https://github.com/t1mt/spegel/blob/dev-0.0.30/internal/kubernetes/kubernetes.go"
    click D1 "https://github.com/t1mt/spegel/tree/dev-0.0.30/charts/spegel"
    click D2 "https://github.com/t1mt/spegel/tree/dev-0.0.30/Dockerfile"
    click D3 "https://github.com/t1mt/spegel/blob/dev-0.0.30/Dockerfile.dev"

    %% Styles
    classDef external fill:#FFD700,stroke:#333,stroke-width:2px;
    classDef service fill:#8FBC8F,stroke:#333,stroke-width:2px;
    classDef module fill:#87CEFA,stroke:#333,stroke-width:2px;
    classDef auxiliary fill:#FF7F7F,stroke:#333,stroke-width:2px;
    classDef k8s fill:#DDA0DD,stroke:#333,stroke-width:2px;
    classDef deployment fill:#C0C0FF,stroke:#333,stroke-width:2px;
```
