# vercel/sdk architecture

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

- Interactive diagram: https://gitdiagram.com/vercel/sdk
- Repository: https://github.com/vercel/sdk

## Overview

##### Project type and purpose
- Type: A TypeScript client‐library + CLI server for the Vercel REST API
- Purpose: Provide type‐safe SDK methods and standalone functions to invoke Vercel API operations, and expose those methods as an MCP server for AI integrations

A. Code Generation Pipeline
– Speakeasy config files (`.speakeasy/gen.yaml`, `.speakeasy/workflow.yaml`)
– GitHub workflows (`.github/workflows/sdk_generation.yaml`, etc.)
B. Core SDK Library (TypeScript)
– `src/lib`: HTTP client wrapper, common utilities, retry logic
– `src/core.ts` + `src/index.ts`: SDK client entry point
– `src/models`: Typed data models and operation input/output definitions
– `src/funcs`: Standalone function implementations (one per API operation)
– `src/sdk`: Namespaced SDK wrapper methods (e.g. `new Vercel().projects.createProject`)
– `src/hooks`: Extension points for HTTP or registration hooks
C. MCP Server (CLI)
– `src/mcp-server`: CLI entry (`cli.ts`), server implementation (`server.ts`), prompts, console‐logger, extension loading
– `src/mcp-server/tools`: Same functions as `src/funcs`, but wired to accept CLI inputs/outputs
D. Documentation
– `docs/models` (one `.md` per model)
– `docs/sdks` (per‐resource README pages)
– Top‐level markdown (README.md, USAGE.md, FUNCTIONS.md, etc.)
E. Test Suite
– `src/__tests__`: TypeScript integration tests invoking both `src/funcs` and `src/sdk`
– `src/__tests__/mockserver`: Go‐based HTTP mock server, with its own internal handlers, logging, templates, and Dockerfile
F. CI/CD & Release
– GitHub Actions (generate SDK, run tests, publish packages)
– `package.json`, lockfiles, devcontainer configuration

##### Relationships and data flows
1. Codegen → produces `src/models`, `src/funcs`, `src/sdk`, `src/mcp-server/tools`
2. Core SDK Library calls HTTP client → Vercel API endpoints
3. Standalone functions & SDK methods use HTTP client + models
4. MCP Server wraps standalone functions, exposes them via CLI or Wire Protocol
5. Tests spin up mockserver (Go) → intercept HTTP calls from SDK to validate behavior
6. Documentation is generated from the same codegen inputs + markdown templates
7. CI workflows glue everything: trigger codegen → build → test → publish

##### Architectural patterns & design principles
- Code‐first, generator‐driven: Speakeasy codegen
- Layered: Models → Functions → SDK client → CLI
- Single HTTP client abstraction with hook pattern
- Tree‐shakable standalone functions for minimal bundles
- MCP server as an adapter pattern for AI tool invocation

##### Technologies & frameworks
- TypeScript (ESM modules)
- Node.js v20+ (HTTP, streams, Blob API)
- Go (mockserver for tests)
- Speakeasy (code generator)
- GitHub Actions (CI/CD)
- Docker (mockserver)
- Zod (optional runtime validation, peer dependency)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Generation Layer
    subgraph "Code Generation Pipeline"
        direction TB
        gen1[".speakeasy/gen.yaml"]:::generation
        gen2[".speakeasy/workflow.yaml"]:::generation
        gen3[".github/workflows/sdk_generation.yaml"]:::generation
    end

    %% CI/CD Layer
    subgraph "CI/CD & Release"
        direction TB
        ci1[".github/workflows/sdk_test.yaml"]:::ci
        ci2[".github/workflows/sdk_publish.yaml"]:::ci
        ci3["package.json"]:::ci
        ci4["package-lock.json / pnpm-lock.yaml"]:::ci
        ci5[".devcontainer"]:::ci
    end

    %% Core SDK Library
    subgraph "Core SDK Library"
        direction TB
        coreLib["src/lib"]:::library
        coreEntry["src/core.ts"]:::library
        coreExport["src/index.ts"]:::library
        models["src/models"]:::library
        funcs["src/funcs"]:::library
        sdkWrap["src/sdk"]:::library
        hooks["src/hooks"]:::library
        httpClient["HTTP Client"]:::library
    end

    %% MCP Server CLI
    subgraph "MCP Server (CLI)"
        direction TB
        cli["src/mcp-server/cli.ts"]:::cli
        server["src/mcp-server/server.ts"]:::cli
        prompts["src/mcp-server/prompts.ts"]:::cli
        logger["src/mcp-server/console-logger.ts"]:::cli
        extLoad["src/mcp-server/extensions.ts"]:::cli
        tools["src/mcp-server/tools"]:::cli
    end

    %% Documentation
    subgraph "Documentation"
        direction TB
        docTop["README.md, USAGE.md, FUNCTIONS.md"]:::docs
        docModels["docs/models"]:::docs
        docSdks["docs/sdks"]:::docs
    end

    %% Test Suite
    subgraph "Test Suite"
        direction TB
        tests["src/__tests__"]:::test
        mockDir["src/__tests__/mockserver"]:::test
        mockServer["Mock Server (Docker)"]:::external
    end

    %% External Services
    subgraph "External Services"
        direction TB
        vercelAPI["Vercel REST API"]:::external
    end

    %% Relationships
    gen1 -->|generates| models
    gen1 -->|generates| funcs
    gen1 -->|generates| sdkWrap
    gen1 -->|generates| tools

    ci1 -->|runs codegen/tests| gen1
    ci1 -->|runs tests| tests
    ci2 -->|publishes package| coreExport

    funcs -->|uses| httpClient
    sdkWrap -->|uses| httpClient
    httpClient -->|calls| vercelAPI

    tests -->|spins up| mockServer
    mockServer -->|intercepts| httpClient

    cli -->|wraps| funcs
    server -->|exposes| funcs
    tools -->|wired to| funcs

    docTop -->|documents| models
    docSdks -->|documents| sdkWrap
    docModels -->|documents| models

    %% Click Events
    click gen1 "https://github.com/vercel/sdk/blob/main/.speakeasy/gen.yaml"
    click gen2 "https://github.com/vercel/sdk/blob/main/.speakeasy/workflow.yaml"
    click gen3 "https://github.com/vercel/sdk/blob/main/.github/workflows/sdk_generation.yaml"
    click ci1 "https://github.com/vercel/sdk/blob/main/.github/workflows/sdk_test.yaml"
    click ci2 "https://github.com/vercel/sdk/blob/main/.github/workflows/sdk_publish.yaml"
    click ci3 "https://github.com/vercel/sdk/blob/main/package.json"
    click ci4 "https://github.com/vercel/sdk/blob/main/package-lock.json / pnpm-lock.yaml"
    click ci5 "https://github.com/vercel/sdk/blob/main/.devcontainer"
    click coreLib "https://github.com/vercel/sdk/tree/main/src/lib"
    click coreEntry "https://github.com/vercel/sdk/blob/main/src/core.ts"
    click coreExport "https://github.com/vercel/sdk/blob/main/src/index.ts"
    click models "https://github.com/vercel/sdk/tree/main/src/models"
    click funcs "https://github.com/vercel/sdk/tree/main/src/funcs"
    click sdkWrap "https://github.com/vercel/sdk/tree/main/src/sdk"
    click hooks "https://github.com/vercel/sdk/tree/main/src/hooks"
    click cli "https://github.com/vercel/sdk/blob/main/src/mcp-server/cli.ts"
    click server "https://github.com/vercel/sdk/blob/main/src/mcp-server/server.ts"
    click prompts "https://github.com/vercel/sdk/blob/main/src/mcp-server/prompts.ts"
    click logger "https://github.com/vercel/sdk/blob/main/src/mcp-server/console-logger.ts"
    click extLoad "https://github.com/vercel/sdk/blob/main/src/mcp-server/extensions.ts"
    click tools "https://github.com/vercel/sdk/tree/main/src/mcp-server/tools"
    click docModels "https://github.com/vercel/sdk/tree/main/docs/models"
    click docSdks "https://github.com/vercel/sdk/tree/main/docs/sdks"
    click tests "https://github.com/vercel/sdk/tree/main/src/__tests__"
    click mockDir "https://github.com/vercel/sdk/tree/main/src/__tests__/mockserver"

    %% Styles
    classDef generation fill:#ffa500,stroke:#333,stroke-width:1px
    classDef ci fill:#ffeb99,stroke:#333,stroke-width:1px
    classDef library fill:#bbdefb,stroke:#333,stroke-width:1px
    classDef cli fill:#c8e6c9,stroke:#333,stroke-width:1px
    classDef test fill:#ffcdd2,stroke:#333,stroke-width:1px
    classDef docs fill:#e1bee7,stroke:#333,stroke-width:1px
    classDef external fill:#eeeeee,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5
```
