# cloudflare/ai architecture

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

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

## Overview

##### Project Type and Purpose
- This is a multi-package monorepo (managed by Nx & Changesets) whose goal is to host:
- Two core provider packages for the Vercel AI SDK (“workers-ai-provider” & “ai-gateway-provider”).
- A set of demo applications (mostly Cloudflare Workers + occasional React frontends) demonstrating how to consume Cloudflare AI features on the client side.
- Shared libraries (“libs/…”) for logging, middleware, testing utilities, and general helpers.
- CLI and code-generation tooling (“tools/…”) to scaffold new demos and manage README publications.

##### Key Elements from the File Structure
- Root Configuration: nx.json, pnpm-workspace.yaml, tsconfig.*.json, .github/* workflows, Changesets.
- packages/: Two npm libraries implementing AI providers.
- libs/: Internal shared code (logger, middleware, utils, test-utils).
- demos/: Dozens of independent demo apps. Each is its own workspace project with:
- Worker code (src/index.ts + Hono types)
- Optional frontend (React + Vite)
- Test configurations (Vitest)
- Wrangler configuration for Cloudflare Workers.
- tools/:
- aicli – a CLI binary for AI workflows.
- create-demo – templating engine to scaffold new demos.
- readme-generator – automated README creation.
- CI/CD: GitHub Actions under .github/workflows for CI, deploy, release, smoke.

##### How to Represent This
- **Workspace Orchestrator** (Nx + pnpm + Changesets)
- **Core Packages**
- Workers-AI-Provider
- AI-Gateway-Provider
- **Shared Libraries** (logger, middleware, utils, test-utils)
- **Tools** (aicli CLI, create-demo generator, readme-generator)
- **Demo Applications** (grouped by type: pure Worker, Worker+Client)
- **External Services**
- Cloudflare Workers Runtime & Wrangler
- Cloudflare AI Gateway & Workers AI Models
- Vercel AI SDK (consumer of core packages)
- Workspace Orchestrator → builds/tests/lints all Projects
- Core Packages → publish to npm → consumed by Demo Apps and external Vercel AI SDK usage
- Shared Libraries → imported by Core Packages and Demos
- Tools → read monorepo, scaffold demos, generate READMEs
- Demo Apps → deployed to Cloudflare Workers via Wrangler → invoke Cloudflare AI Gateway or Workers AI endpoints
- CLI (aicli) → local user → orchestrates AI calls through Core Packages
c. Architectural Patterns & Principles
- Monorepo with strict project boundaries enforced by Nx
- Layered architecture:
- Infrastructure & Orchestration (Nx, CI/CD)
- Core Business Logic (AI provider packages)
- Cross-cutting Concerns (libs)
- Application Layer (demos)
- Tooling Layer (CLI and scaffolding)
- Dependency graph: libs ← packages ← demos (no cycles).
- Each demo is an independent micro-application (serverless + optional SPA).
d. Key Technologies & Frameworks
- Node.js & TypeScript
- Nx workspace & pnpm for multi-package management
- Changesets for versioning & release automation
- Cloudflare Workers + Wrangler (serverless)
- Hono (HTTP framework in Workers)
- Vite + React for SPA frontends
- Vitest for unit & smoke tests
- Vercel AI SDK for upstream consumption

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Orchestration Layer
    WorkspaceOrchestrator["Workspace Orchestrator\n(Nx, pnpm, Changesets)"]:::orchestration

    %% Core Packages
    subgraph "Core Packages"
        WorkersAIProvider["workers-ai-provider\n(TypeScript)"]:::core
        AIGatewayProvider["ai-gateway-provider\n(TypeScript)"]:::core
    end

    %% Shared Libraries
    subgraph "Shared Libraries"
        Logger["logger"]:::shared
        Middleware["middleware"]:::shared
        Utils["utils"]:::shared
        TestUtils["test-utils"]:::shared
    end

    %% Tools Layer
    subgraph "Tools"
        AICLI["aicli CLI"]:::tools
        CreateDemo["create-demo Generator"]:::tools
        ReadmeGen["readme-generator"]:::tools
    end

    %% Demo Applications
    subgraph "Demo Applications"
        WorkerOnly["Pure Worker Demos"]:::demos
        WorkerClient["Worker+Client Demos"]:::demos
    end

    %% External Services
    CFWorkers["Cloudflare Workers Runtime & Wrangler"]:::external
    CFAI["Cloudflare AI Gateway & Models"]:::external
    VercelAI["Vercel AI SDK"]:::external

    %% Build/Test Flows
    WorkspaceOrchestrator -->|build/test/lint| WorkersAIProvider
    WorkspaceOrchestrator -->|build/test/lint| AIGatewayProvider
    WorkspaceOrchestrator -->|build/test/lint| Logger
    WorkspaceOrchestrator -->|build/test/lint| Middleware
    WorkspaceOrchestrator -->|build/test/lint| Utils
    WorkspaceOrchestrator -->|build/test/lint| TestUtils
    WorkspaceOrchestrator -->|build/test/lint| AICLI
    WorkspaceOrchestrator -->|build/test/lint| CreateDemo
    WorkspaceOrchestrator -->|build/test/lint| ReadmeGen
    WorkspaceOrchestrator -->|build/test/lint| WorkerOnly
    WorkspaceOrchestrator -->|build/test/lint| WorkerClient

    %% Dependencies
    Logger --> WorkersAIProvider
    Middleware --> WorkersAIProvider
    Utils --> WorkersAIProvider
    TestUtils --> WorkersAIProvider

    Logger --> AIGatewayProvider
    Middleware --> AIGatewayProvider
    Utils --> AIGatewayProvider
    TestUtils --> AIGatewayProvider

    %% Core to Demos & External
    WorkersAIProvider -->|npm publish / consume| VercelAI
    AIGatewayProvider -->|npm publish / consume| VercelAI

    WorkersAIProvider --> WorkerOnly
    AIGatewayProvider --> WorkerOnly
    WorkersAIProvider --> WorkerClient
    AIGatewayProvider --> WorkerClient

    WorkerOnly -->|deploy via Wrangler| CFWorkers
    WorkerClient -->|deploy via Wrangler| CFWorkers

    CFWorkers -->|invoke AI endpoints| CFAI

    %% Tools Usage
    AICLI -->|orchestrate AI calls| WorkersAIProvider
    AICLI -->|orchestrate AI calls| AIGatewayProvider

    CreateDemo -->|scaffold projects| WorkerOnly
    CreateDemo -->|scaffold projects| WorkerClient

    ReadmeGen -->|generate docs| WorkerOnly
    ReadmeGen -->|generate docs| WorkerClient

    %% Click Events
    click WorkspaceOrchestrator "https://github.com/cloudflare/ai/blob/main/nx.json"
    click WorkersAIProvider "https://github.com/cloudflare/ai/tree/main/packages/workers-ai-provider/"
    click AIGatewayProvider "https://github.com/cloudflare/ai/tree/main/packages/ai-gateway-provider/"
    click Logger "https://github.com/cloudflare/ai/tree/main/libs/logger/"
    click Middleware "https://github.com/cloudflare/ai/tree/main/libs/middleware/"
    click Utils "https://github.com/cloudflare/ai/tree/main/libs/utils/"
    click TestUtils "https://github.com/cloudflare/ai/tree/main/libs/test-utils/"
    click AICLI "https://github.com/cloudflare/ai/tree/main/tools/aicli/"
    click CreateDemo "https://github.com/cloudflare/ai/tree/main/tools/create-demo/"
    click ReadmeGen "https://github.com/cloudflare/ai/tree/main/tools/readme-generator/"

    %% Styles
    classDef orchestration fill:#D8BFD8,stroke:#8B008B,color:#000
    classDef core fill:#ADD8E6,stroke:#0000CD,color:#000
    classDef shared fill:#90EE90,stroke:#008000,color:#000
    classDef tools fill:#FFDAB9,stroke:#FF8C00,color:#000
    classDef demos fill:#D3D3D3,stroke:#696969,color:#000
    classDef external fill:#FFC0CB,stroke:#FF0000,color:#000
```
