# cloudflare/serverless-registry architecture

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

- Interactive diagram: https://gitdiagram.com/cloudflare/serverless-registry
- Repository: https://github.com/cloudflare/serverless-registry

## Overview

##### Project Type and Purpose
- This is a cloud-based container registry deployed as a Workers application.
- It handles Docker image push/pull operations and includes mechanisms for handling large image layers and fallback to external registries.
- The README emphasizes deployment using the wrangler CLI, configuration of R2 buckets, and using secrets for authentication.

##### Analysis of the File Tree
- Top-level files (e.g., index.ts, package.json) and configuration scripts (.prettierrc.js, tsconfig.json, etc.) indicate a TypeScript project.
- The “src” directory holds the main application code including:
- src/auth.ts and src/authentication-method.ts for authentication logic.
- src/registry subfolder with multiple files (garbage-collector.ts, http.ts, r2.ts, registry.ts) that encapsulate the registry operations and interactions with R2.
- src/router.ts which likely maps endpoints for the registry API.
- Additional files (e.g., errors.ts, token.ts, user.ts) for error handling and user management.
- The “push” folder reflects specialized push operations for handling large layers or other push-related workflows, including its own index.ts, limiter.ts, and README.
- Test files under “test/” and GitHub workflows indicate automated testing and CI support.

##### Key Components
a. External Clients:
- Docker clients executing commands like push, pull, login.
b. Cloudflare Workers:
- The main Workers execution environment represented by the index.ts entry point.
- A component labeled “Router” (from src/router.ts) directing incoming API requests to appropriate submodules.
c. Authentication Module:
- Components for username/password handling (src/auth.ts) and JWT verification (src/authentication-method.ts).
d. Registry Module:
- A central “Registry” component (src/registry/registry.ts) that handles the core push and pull logic.
- Modules for R2 interactions (src/registry/r2.ts) to show the direct link between the registry logic and the R2 data store.
- Garbage collection logic (src/registry/garbage-collector.ts) to represent maintenance tasks.
- Also incorporate the HTTP communication aspects (src/registry/http.ts) that manage external API interactions.
e. Push Workflow:
f. External Registry Fallback:
- An optional component representing external registries. Show how a request not satisfied by the R2 bucket is forwarded to an external registry (as described in the README) and then cached in R2.
g. Storage:

##### Technologies, Frameworks, and Deployment Configurations
- Clearly label Cloudflare Workers as the deployment runtime.
- Use of an R2 Bucket for storage and highlight the connection via the API calls in the registry modules.
- Mention that deployment, testing, and CI/CD processes are managed by wrangler and GitHub Workflows (referenced by the .github directory).

## Diagram (Mermaid)

```mermaid
flowchart TD
    extClients["Docker Clients"]:::external
    CW["Cloudflare Workers - Entry (index.ts)"]:::worker
    Router["Router - API Mapping (src/router.ts)"]:::api

    subgraph "Authentication Service"
        AuthUser["Username/Password Auth (src/auth.ts)"]:::auth
        AuthJWT["JWT Verification (src/authentication-method.ts)"]:::auth
    end

    Registry["Registry Core Service (src/registry/registry.ts)"]:::service
    R2Inter["R2 Interaction Module (src/registry/r2.ts)"]:::db
    HTTPHandler["HTTP Communication Handler (src/registry/http.ts)"]:::service
    Garbage["Garbage Collection (src/registry/garbage-collector.ts)"]:::utility

    subgraph "Push Workflow"
        PushMain["Push Main (push/index.ts)"]:::service
        PushLimiter["Push Limiter (push/limiter.ts)"]:::service
    end

    R2Bucket["R2 Bucket"]:::storage
    extRegistry["External Registry Fallback"]:::external

    %% Connections
    extClients -->|"HTTPrequest"| CW
    CW -->|"Routes"| Router
    Router -->|"Auth"| AuthUser
    Router -->|"Auth"| AuthJWT
    Router -->|"RegistryOps"| Registry
    Router -->|"LargeUploads"| PushMain
    Router -->|"LargeUploads"| PushLimiter

    Registry -->|"R2Ops"| R2Inter
    R2Inter -->|"ReadWrite"| R2Bucket
    Registry -->|"HTTPcalls"| HTTPHandler
    HTTPHandler -->|"Fallback"| extRegistry
    Registry -->|"Trigger"| Garbage

    PushMain -->|"UploadOps"| R2Bucket
    PushLimiter -->|"RateLimit"| R2Bucket

    %% Click Events
    click CW "https://github.com/cloudflare/serverless-registry/blob/main/index.ts"
    click Router "https://github.com/cloudflare/serverless-registry/blob/main/src/router.ts"
    click AuthUser "https://github.com/cloudflare/serverless-registry/blob/main/src/auth.ts"
    click AuthJWT "https://github.com/cloudflare/serverless-registry/blob/main/src/authentication-method.ts"
    click Registry "https://github.com/cloudflare/serverless-registry/blob/main/src/registry/registry.ts"
    click R2Inter "https://github.com/cloudflare/serverless-registry/blob/main/src/registry/r2.ts"
    click HTTPHandler "https://github.com/cloudflare/serverless-registry/blob/main/src/registry/http.ts"
    click Garbage "https://github.com/cloudflare/serverless-registry/blob/main/src/registry/garbage-collector.ts"
    click PushMain "https://github.com/cloudflare/serverless-registry/blob/main/push/index.ts"
    click PushLimiter "https://github.com/cloudflare/serverless-registry/blob/main/push/limiter.ts"

    %% Styles
    classDef external fill:#ffcc00,stroke:#333,stroke-width:2px;
    classDef worker fill:#ff9999,stroke:#333,stroke-width:2px;
    classDef api fill:#99ccff,stroke:#333,stroke-width:2px;
    classDef auth fill:#ccffcc,stroke:#333,stroke-width:2px;
    classDef service fill:#ffccff,stroke:#333,stroke-width:2px;
    classDef db fill:#ffff99,stroke:#333,stroke-width:2px;
    classDef storage fill:#ccffff,stroke:#333,stroke-width:2px;
    classDef utility fill:#ccccff,stroke:#333,stroke-width:2px;
```
