# seqeralabs/wave architecture

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

## Overview

##### Main Components
a. API / Controller Layer: Representing REST endpoints that include endpoints like POST /container-token. The controllers (e.g., BuildController, ContainerController, MetricsController, etc.) expose the service to Docker clients and the Wave CLI.
b. Authentication & Authorization Module: Shows modules handling authentication for various registries (e.g., BasicAuthenticationProvider, RegistryAuthService, RegistryCredentialsProvider) which secure access and token management.
c. Container Build & Augmentation Services: Illustrate the service(s) that build or augment images on demand. This includes services related to building container images using given Dockerfiles or Conda packages (seen in the service/builder package) and those for image augmentation (modules in wave/core and blob).
d. Proxy Service: Since disposable containers act as a proxy, include the component that instruments the manifest and redirects container pull requests (e.g., RegistryProxyController and related service components).
e. Blob & Cache Management: The blob service (e.g., BlobCacheService, BlobSigningService) manages caching of built images and signed URLs for secure downloads. Also include caching components that interact with Redis and other storage backends.
f. Rate Limiting & Monitoring: Given the ratelimit packages (e.g., RateLimiterFilter, SpillwayRateLimiter) and metrics controllers/service components, show how incoming requests are throttled and monitored.
g. External Dependencies & Integrations:
- Container Registries: Outbound connections to various registries (Docker Hub, Quay, AWS ECR, AzureCR).
- Redis: Used for caching, rate limiting, state stores, and message queues.
- Kubernetes: Utilized for production deployment and possibly for container builds (as indicated in the README and service/k8s packages).
- Other External Tools: Reference to the Wave CLI, and external vulnerabilities scanners or manifest APIs.

##### Relationships and Interactions
- The API/Controller layer receives requests for container provisioning. It validates and authenticates incoming requests by consulting the Authentication Module.
- A request for building or augmenting an image is forwarded to the Build Service. This service may use either Docker or Kubernetes build strategies, interacting with Blob Management to retrieve/push container layers.
- For disposable requests, the Proxy Service engages by intercepting the container pull flow, rewriting image manifests, and routing layer downloads between the Docker client and the external registries.
- Caching, state management, and rate limiting services (using Redis) intersect with the Build, Scan, and Proxy services to improve performance and provide resilience.
- Monitoring and metrics components gather performance and usage statistics that flow back to the Metrics Controller for observability.
- External integrations (container registries, cloud storage, etc.) are depicted as external systems that exchange data via defined protocols (e.g., Docker registry v2 API).

##### Architectural Patterns and Design Principles
- A layered/microkernel pattern is evident where API/Controllers, Services, and Utility/Infrastructure layers are clearly separated.
- Modular design: The codebase is divided into many well-defined packages (auth, builder, blob, counter, etc.) that help in understanding and extending functionality.
- Integration of external services via adapters or factory patterns (e.g., RegistryCredentialsFactory, RedisFactory) promotes loose coupling.
- Use of interception and filter patterns (like in the filters directory) to manage cross-cutting concerns such as tracing, logging, and rate limiting.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Client
    Client["Docker Client / Wave CLI"]:::external

    %% API and Access Layer
    subgraph "API and Access Layer"
        A1["API/Controller Layer"]:::api
        A2["Authentication Module"]:::auth
    end

    %% Service Layer
    subgraph "Service Layer"
        S1["Build Service"]:::service
        S2["Image Augmentation"]:::service
        subgraph "Proxy Service"
            P1["RegistryProxyController"]:::proxy
            P2["RegistryProxyService"]:::proxy
        end
        S4["Blob & Cache Management"]:::cache
        S5["Rate Limiter"]:::ratelimit
        S6["Metrics Controller"]:::metrics
    end

    %% External Dependencies
    subgraph "External Dependencies"
        E1["Kubernetes Integration"]:::external
        E2["Redis Configuration"]:::external
        E3["Container Registries"]:::external
        
        subgraph "Build & Deployment Infra"
            E41["Gradle Build System"]:::external
            E42["CI/CD Workflows"]:::external
        end
    end

    %% Connections from Client
    Client -->|"HTTP_Request"| A1

    %% Connections within API Layer
    A1 -->|"authenticates"| A2

    %% API to Service Layer
    A1 -->|"build_request"| S1
    A1 -->|"augment_request"| S2
    A1 -->|"proxy_request"| P1
    A1 -->|"rate_limit"| S5
    A1 -->|"metrics_logging"| S6

    %% Proxy internal flow
    P1 -->|"delegates"| P2

    %% Service Layer internal flows
    S1 -->|"uses"| S4
    S2 -->|"uses"| S4

    %% Interactions with External Dependencies
    S1 -->|"builds_on"| E1
    S4 -->|"caches_to"| E2
    P2 -->|"redirects_to"| E3

    %% Metrics flow
    S5 -->|"reports"| S6

    %% Build & Deployment triggers
    E41 -->|"build_triggered"| S1
    E42 -->|"deploy_triggered"| S2

    %% Click Events
    click A1 "https://github.com/seqeralabs/wave/tree/master/src/main/groovy/io/seqera/wave/controller"
    click A2 "https://github.com/seqeralabs/wave/tree/master/src/main/groovy/io/seqera/wave/auth"
    click S1 "https://github.com/seqeralabs/wave/tree/master/src/main/groovy/io/seqera/wave/service/builder"
    click S2 "https://github.com/seqeralabs/wave/blob/master/src/main/groovy/io/seqera/wave/core/ContainerAugmenter.groovy"
    click P1 "https://github.com/seqeralabs/wave/blob/master/src/main/groovy/io/seqera/wave/controller/RegistryProxyController.groovy"
    click P2 "https://github.com/seqeralabs/wave/blob/master/src/main/groovy/io/seqera/wave/core/RegistryProxyService.groovy"
    click S4 "https://github.com/seqeralabs/wave/tree/master/src/main/groovy/io/seqera/wave/service/blob"
    click S5 "https://github.com/seqeralabs/wave/tree/master/src/main/groovy/io/seqera/wave/ratelimit"
    click S6 "https://github.com/seqeralabs/wave/blob/master/src/main/groovy/io/seqera/wave/controller/MetricsController.groovy"
    click E1 "https://github.com/seqeralabs/wave/tree/master/src/main/groovy/io/seqera/wave/service/k8s"
    click E2 "https://github.com/seqeralabs/wave/blob/master/src/main/groovy/io/seqera/wave/configuration/RedisConfig.groovy"
    click E41 "https://github.com/seqeralabs/wave/blob/master/build.gradle"
    click E41 "https://github.com/seqeralabs/wave/tree/master/buildSrc"
    click E42 "https://github.com/seqeralabs/wave/tree/master/.github/workflows"

    %% Styles
    classDef api fill:#f9c74f,stroke:#000,stroke-width:2px;
    classDef auth fill:#90be6d,stroke:#000,stroke-width:2px;
    classDef service fill:#f9844a,stroke:#000,stroke-width:2px;
    classDef proxy fill:#577590,stroke:#fff,stroke-width:2px;
    classDef cache fill:#43aa8b,stroke:#000,stroke-width:2px;
    classDef ratelimit fill:#f94144,stroke:#000,stroke-width:2px;
    classDef metrics fill:#277da1,stroke:#fff,stroke-width:2px;
    classDef external fill:#6a4c93,stroke:#fff,stroke-width:2px;
```
