# cloudflare/api-schemas architecture

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

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

## Overview

##### Project type and purpose
- This is not a runtime application but an “API‐as‐code” repository: it holds the OpenAPI schemas for the Cloudflare API (both YAML and JSON variants), plus shared/common definitions.
- Its main purpose is to version, validate, lint, and publish API schemas as source artifacts that downstream tools (e.g., documentation generators, client‐SDK generators) can consume.

##### File structure
- Top‐level artifacts:
– openapi.yaml / openapi.json – the canonical API specification files
– common.yaml – reusable components (schemas, parameters) imported by the main spec
- CI/CD and automation:
– .github/workflows/semgrep.yml – security/static‐analysis scans on schema files
– .github/workflows/stainless.yml – policy checks (e.g., style/lint rules via Stainless)
– .redocly.lint-ignore.yaml – exceptions for the Redocly linter
- Supporting files:
– common.yaml is imported by openapi.yaml; openapi.json can be generated from the YAML or vice versa
– README.md describes the repository’s purpose; LICENSE governs usage

##### Key insights from README
- “Contains OpenAPI schemas for the Cloudflare API.”
- It’s a central source of truth for all API definitions—not a service implementation.

##### Main components
a. Repository (GitHub)
b. Schema source files (openapi.yaml, common.yaml)
c. CI/CD workflows (GitHub Actions runners)
d. Linters and Validators (Redocly CLI, Semgrep, Stainless)
e. Generated artifacts (openapi.json, versioned spec bundles)
f. Consumers: documentation site generator, SDK generators, downstream services/clients

##### Relationships & interactions
- Commits/PRs in GitHub → trigger GitHub Actions →
- Semgrep workflow scans YAML/JSON for security issues
- Stainless workflow enforces style/policy rules
- Redocly linter runs (locally or in CI) against openapi.yaml + common.yaml
- On successful validation, a CI job can publish or bundle artifacts (openapi.json, NPM package, CDN upload)
- Downstream tools (SDK generators, documentation sites) pull the published spec

##### Architectural patterns & principles
- Specification-as-code: treat API definitions like application code (versioned, reviewed, tested)
- Modular schemas: common.yaml houses shared components to keep the spec DRY
- CI-driven validation: gate every change with automated checks (security, style, compliance)
- Publish-on-merge: every merged PR produces consumable artifacts for downstream use

##### Final advice
- Be meticulous in naming each file or component—accuracy is critical for a spec repo.
- CI‐driven gates (lint, security, policy) that protect the canonical API definitions.
- Both the static structure (files and their imports) and the dynamic flows (CI triggers, publishing).
- Use legends or notes to explain any non‐obvious relationships (e.g., why common.yaml is separate).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Repository Root and Source Artifacts
    Repo["GitHub Repository"]:::repo
    subgraph "Source Artifacts"
        direction TB
        Common["common.yaml"]:::source
        OpenAPI["openapi.yaml"]:::source
        RedoclyIgnore[".redocly.lint-ignore.yaml"]:::config
        Readme["README.md"]:::doc
        License["LICENSE"]:::doc
        Gitignore[".gitignore"]:::config
    end

    %% CI/CD Workflows
    subgraph "CI/CD Workflows"
        direction TB
        Semgrep["Semgrep Security Scans"]:::ci
        Stainless["Stainless Policy Checks"]:::ci
    end

    %% Validation Tools
    subgraph "Validation Tools"
        direction TB
        Redocly["Redocly Linter"]:::validator
    end

    %% Generated Artifacts and Publishing
    subgraph "Artifacts & Publishing"
        direction TB
        APIJSON["openapi.json"]:::artifact
        Publish["Publish to NPM/CDN"]:::ci
    end

    %% Consumers
    subgraph "Consumers"
        direction TB
        SDK["SDK Generators"]:::consumer
        Docs["Documentation Site Generator"]:::consumer
        Downstream["Downstream Services/Clients"]:::consumer
    end

    %% Imports and Relationships
    Common -->|"imported by"| OpenAPI
    Repo -->|"contains"| Common
    Repo -->|"contains"| OpenAPI
    Repo -->|"contains"| RedoclyIgnore
    Repo -->|"contains"| Readme
    Repo -->|"contains"| License
    Repo -->|"contains"| Gitignore

    %% CI Triggers
    Repo -->|"push/PR triggers"| Semgrep
    Repo -->|"push/PR triggers"| Stainless

    %% CI to Validation
    Semgrep -->|"security scan"| Repo
    Stainless -->|"style/policy check"| Repo
    Semgrep --> Redocly
    Stainless --> Redocly

    %% Linting
    OpenAPI -->|"lint"| Redocly
    Common -->|"lint dependencies"| Redocly

    %% On Success Publish
    Redocly -->|"validate and bundle"| APIJSON
    APIJSON --> Publish

    %% Consumption
    Publish -->|"consume"| SDK
    Publish -->|"consume"| Docs
    Publish -->|"consume"| Downstream

    %% Click Events
    click Repo "https://github.com/cloudflare/api-schemas/tree/main//"
    click Common "https://github.com/cloudflare/api-schemas/blob/main//common.yaml"
    click OpenAPI "https://github.com/cloudflare/api-schemas/blob/main//openapi.yaml"
    click APIJSON "https://github.com/cloudflare/api-schemas/blob/main//openapi.json"
    click Semgrep "https://github.com/cloudflare/api-schemas/blob/main//.github/workflows/semgrep.yml"
    click Stainless "https://github.com/cloudflare/api-schemas/blob/main//.github/workflows/stainless.yml"
    click RedoclyIgnore "https://github.com/cloudflare/api-schemas/blob/main//.redocly.lint-ignore.yaml"
    click Readme "https://github.com/cloudflare/api-schemas/blob/main//README.md"
    click License "https://github.com/cloudflare/api-schemas/tree/main//LICENSE"
    click Gitignore "https://github.com/cloudflare/api-schemas/blob/main//.gitignore"

    %% Styles
    classDef repo fill:#f8f9fa,stroke:#343a40,stroke-width:2px,color:#343a40;
    classDef source fill:#cfe2ff,stroke:#0d6efd,stroke-width:1px,color:#0d6efd;
    classDef config fill:#e2e3e5,stroke:#6c757d,stroke-width:1px,color:#6c757d;
    classDef doc fill:#fff3cd,stroke:#ffc107,stroke-width:1px,color:#856404;
    classDef ci fill:#d1e7dd,stroke:#198754,stroke-width:1px,color:#198754;
    classDef validator fill:#ffe5d9,stroke:#ff6b6b,stroke-width:1px,color:#ff6b6b;
    classDef artifact fill:#d6d8f9,stroke:#6f42c1,stroke-width:1px,color:#6f42c1;
    classDef consumer fill:#e2e3f3,stroke:#6610f2,stroke-width:1px,color:#6610f2;
```
