# openai/openai-cookbook architecture

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

- Interactive diagram: https://gitdiagram.com/openai/openai-cookbook
- Repository: https://github.com/openai/openai-cookbook
- Video tour (about a minute): https://gitdiagram.com/openai/openai-cookbook/video

## Overview

1. **What this repository is**
   This is the OpenAI Cookbook: a content-and-examples repository, not a single application. Its primary purpose is to publish runnable examples, guides, and evaluations for the OpenAI API, then surface them on the cookbook website.

2. **Top-level architecture**
   The repo is organized around three broad layers:
   - **Published content**: `articles/`, `examples/`, and some `mdx`/`md` guides.
   - **Supporting assets and data**: `examples/data/`, `images/`, and example-specific datasets.
   - **Site/quality automation**: `.github/workflows/`, notebook validation, and schema files.

3. **Content model**
   The content is heterogeneous:
   - **Jupyter notebooks** are the dominant format for runnable tutorials.
   - **Markdown/MDX articles** provide conceptual guides and long-form explanations.
   - **Code-first mini projects** live in nested example folders with their own scripts, configs, and sometimes UIs.
   This means the architecture is more like a documentation platform plus example workspace than a conventional service repo.

4. **Website publishing boundary**
   The repo appears to be built for publication to `cookbook.openai.com`. The website pipeline is driven by repository content and metadata rather than by an application backend. The root `registry.yaml` and `.github/registry_schema.json`/`authors_schema.json` suggest a content registry and metadata validation layer for what gets published and how it is attributed.

5. **Example ecosystem**
   `examples/` is the largest subsystem and contains many independent solution paths: embeddings, fine-tuning, agents, RAG, speech, multimodal, evaluations, vector databases, partner integrations, and more. Each example is typically self-contained with its own notebook, sometimes supporting Python modules, sometimes data files, and occasionally container or cloud deployment assets.

6. **Reusable libraries vs. one-off projects**
   Most examples are intentionally isolated, but some subdirectories introduce reusable helper code:
   - `examples/utils/` for shared utilities
   - `examples/api_request_parallel_processor.py` and other standalone scripts
   - Example-local modules such as `examples/agents_sdk/.../investment_agents/` or `examples/evals/.../shared/`
   This creates a hybrid structure: common helpers exist, but the repo favors example-local ownership over a monorepo-style shared application library.

7. **Evaluation and benchmarking subsystem**
   `examples/evals/` and `examples/evaluation/` are a distinct architecture slice focused on testing model behavior, prompt quality, and agent/realtime workflows. These folders include:
   - harnesses
   - graders
   - plotting/reporting utilities
   - test fixtures and synthetic datasets
   - result viewers
   This subsystem is more operational than tutorial-oriented and is meant to generate repeatable metrics and reports.

8. **Agent, MCP, and real-time solution patterns**
   Several folders demonstrate system-level integrations:
   - `examples/agents_sdk/` for multi-agent and voice-agent patterns
   - `examples/mcp/` for Model Context Protocol-style tool servers and agent integrations
   - `examples/voice_solutions/` for realtime speech/translation experiences
   These projects often include both backend services and front-end clients, showing the repo is not only notebook-based but also a source of deployable reference architectures.

9. **External service and infrastructure boundaries**
   Many examples depend on external runtimes or services, but those dependencies are example-specific rather than shared platform infrastructure. Common boundaries include:
   - OpenAI API access
   - vector databases and search engines
   - cloud functions or serverless runtimes
   - Streamlit, React/Vite, or notebook execution environments
   - local data stores such as SQLite or files for demo purposes
   The repository itself does not centralize these services; each example wires them in independently.

10. **Data and assets**
   `examples/data/` is a large shared fixture library with PDFs, CSVs, JSONL, audio, images, and text corpora used across tutorials. Many subprojects also carry their own bundled assets. This indicates the repo is designed for reproducible demos: examples are expected to run against packaged sample data, not external proprietary datasets.

11. **Governance and contributor workflow**
   `.github/` contains issue templates, a pull request template, author/registry schemas, and validation workflows. There are explicit checks for notebook formatting/structure and automated website build steps. This suggests a content-review pipeline where notebooks and guides are treated as versioned publishable artifacts.

12. **Practical architecture diagram framing**
   If you draw this repo as an architecture diagram, the central node should be **the Cookbook content repository**, with three major outbound paths:
   - to the **published website**,
   - to **example runtimes and external AI/cloud services**,
   - and to **CI/validation tooling** that enforces content quality before publishing.
   Underneath the content layer, show many isolated example “pods” rather than one shared runtime.

Main entry points: [`examples`](https://github.com/openai/openai-cookbook/tree/main/examples) (Examples), [`articles`](https://github.com/openai/openai-cookbook/tree/main/articles) (Articles), [`examples/evals`](https://github.com/openai/openai-cookbook/tree/main/examples/evals) (Evals Suite), [`examples/agents_sdk`](https://github.com/openai/openai-cookbook/tree/main/examples/agents_sdk) (Agent Systems)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_content["Content"]
  node_articles["Articles<br/>guides"]
  node_notebooks["Notebooks<br/>tutorials"]
  node_md_guides["MDX/MD<br/>narrative guides"]
end

subgraph group_group_examples["Examples"]
  node_examples_root["Examples<br/>example hub"]
  node_shared_utils["Shared Utils<br/>helpers"]
  node_vector_db_examples["Vector DBs<br/>integration family"]
  node_evals_suite["Evals Suite<br/>evaluation system"]
  node_agents_solutions["Agent Systems<br/>agent patterns"]
  node_voice_solutions["Voice Solutions<br/>realtime speech"]
  node_partner_examples["Partner Demos<br/>partner integrations"]
end

subgraph group_group_automation["Automation"]
  node_registry["Registry<br/>content metadata<br/>[registry.yaml]"]
  node_schema_validation["Schemas<br/>metadata schema"]
  node_notebook_ci["Notebook CI<br/>validation workflow"]
  node_website_build["Site Build<br/>publish workflow<br/>[build-website.yaml]"]
  node_content_governance["Contrib flow<br/>review workflow<br/>[.github]"]
end

subgraph group_group_assets["Assets"]
  node_shared_data[("Shared Data<br/>fixtures")]
end

node_repo["Cookbook<br/>content repo"]
node_external_services(("External APIs<br/>service boundary"))
node_published_site["Cookbook Site<br/>website"]

node_repo -->|"contains"| node_articles
node_repo -->|"contains"| node_examples_root
node_repo -->|"declares"| node_registry
node_repo -->|"governs"| node_content_governance
node_registry -->|"validated by"| node_schema_validation
node_notebook_ci -->|"checks"| node_schema_validation
node_website_build -->|"publishes"| node_published_site
node_articles -->|"surfaced on"| node_published_site
node_examples_root -->|"surfaced on"| node_published_site
node_examples_root -->|"dominates"| node_notebooks
node_examples_root -->|"includes"| node_md_guides
node_examples_root -->|"uses"| node_shared_data
node_examples_root -->|"uses"| node_shared_utils
node_examples_root -->|"contains"| node_vector_db_examples
node_examples_root -->|"contains"| node_evals_suite
node_examples_root -->|"contains"| node_agents_solutions
node_examples_root -->|"contains"| node_voice_solutions
node_examples_root -->|"contains"| node_partner_examples
node_examples_root -->|"integrates with"| node_external_services
node_evals_suite -->|"measures"| node_external_services
node_agents_solutions -->|"depends on"| node_external_services
node_voice_solutions -->|"streams to"| node_external_services
node_partner_examples -->|"bridges"| node_external_services

click node_articles "https://github.com/openai/openai-cookbook/tree/main/articles"
click node_examples_root "https://github.com/openai/openai-cookbook/tree/main/examples"
click node_notebooks "https://github.com/openai/openai-cookbook/tree/main/examples"
click node_md_guides "https://github.com/openai/openai-cookbook/tree/main/articles"
click node_registry "https://github.com/openai/openai-cookbook/blob/main/registry.yaml"
click node_schema_validation "https://github.com/openai/openai-cookbook/blob/main/.github/registry_schema.json"
click node_notebook_ci "https://github.com/openai/openai-cookbook/blob/main/.github/workflows/validate-notebooks.yaml"
click node_website_build "https://github.com/openai/openai-cookbook/blob/main/.github/workflows/build-website.yaml"
click node_content_governance "https://github.com/openai/openai-cookbook/blob/main/.github"
click node_shared_data "https://github.com/openai/openai-cookbook/tree/main/examples/data"
click node_shared_utils "https://github.com/openai/openai-cookbook/tree/main/examples/utils"
click node_vector_db_examples "https://github.com/openai/openai-cookbook/tree/main/examples/vector_databases"
click node_evals_suite "https://github.com/openai/openai-cookbook/tree/main/examples/evals"
click node_agents_solutions "https://github.com/openai/openai-cookbook/tree/main/examples/agents_sdk"
click node_voice_solutions "https://github.com/openai/openai-cookbook/tree/main/examples/voice_solutions"
click node_partner_examples "https://github.com/openai/openai-cookbook/tree/main/examples/partners"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_articles,node_notebooks,node_md_guides toneBlue
class node_examples_root,node_shared_utils,node_vector_db_examples,node_evals_suite,node_agents_solutions,node_voice_solutions,node_partner_examples toneAmber
class node_registry,node_schema_validation,node_notebook_ci,node_website_build,node_content_governance toneMint
class node_shared_data toneRose
class node_repo,node_external_services,node_published_site toneNeutral
```

## Components

### Content

Published articles, notebooks, and guides that make up the cookbook surface area.

- [Articles](https://github.com/openai/openai-cookbook/tree/main/articles): guides · Long-form conceptual guides and explanatory content. · `articles`
- [Notebooks](https://github.com/openai/openai-cookbook/tree/main/examples): tutorials · Dominant format for runnable cookbook recipes and walkthroughs. · `examples`
- [MDX/MD](https://github.com/openai/openai-cookbook/tree/main/articles): narrative guides · Markdown and MDX guides that complement notebook examples. · `articles`

### Examples

Runnable example subsystems and reference implementations.

- [Examples](https://github.com/openai/openai-cookbook/tree/main/examples): example hub · Primary collection of runnable notebooks and mini-projects. · `examples`
- [Shared Utils](https://github.com/openai/openai-cookbook/tree/main/examples/utils): helpers · Small shared helper code used by multiple examples. · `examples/utils`
- [Vector DBs](https://github.com/openai/openai-cookbook/tree/main/examples/vector_databases): integration family · Provider-specific retrieval and semantic search examples across many databases. · `examples/vector_databases`
- [Evals Suite](https://github.com/openai/openai-cookbook/tree/main/examples/evals): evaluation system · Operational harnesses for benchmarking, grading, plotting, and result viewing. · `examples/evals`
- [Agent Systems](https://github.com/openai/openai-cookbook/tree/main/examples/agents_sdk): agent patterns · Agent SDK, MCP, and voice-oriented systems with multi-component reference architectures. · `examples/agents_sdk`
- [Voice Solutions](https://github.com/openai/openai-cookbook/tree/main/examples/voice_solutions): realtime speech · Realtime speech, translation, and audio-driven experiences with client and server pieces. · `examples/voice_solutions`
- [Partner Demos](https://github.com/openai/openai-cookbook/tree/main/examples/partners): partner integrations · Examples built around external partner systems, workflow tools, and specialized deployments. · `examples/partners`

### Automation

Registry, schemas, and CI checks that validate and publish content.

- [Registry](https://github.com/openai/openai-cookbook/blob/main/registry.yaml): content metadata · Top-level content registry used to declare publishable items and authorship. · `registry.yaml`
- [Schemas](https://github.com/openai/openai-cookbook/blob/main/.github/registry_schema.json): metadata schema · Registry and author schema files used to validate cookbook content. · `.github/registry_schema.json`
- [Notebook CI](https://github.com/openai/openai-cookbook/blob/main/.github/workflows/validate-notebooks.yaml): validation workflow · Automated notebook checks and notebook-specific validation jobs. · `.github/workflows/validate-notebooks.yaml`
- [Site Build](https://github.com/openai/openai-cookbook/blob/main/.github/workflows/build-website.yaml): publish workflow · CI pipeline that turns repository content into the cookbook website. · `.github/workflows/build-website.yaml`
- [Contrib flow](https://github.com/openai/openai-cookbook/blob/main/.github): review workflow · Issue, pull-request, and contributor guidance for authored content. · `.github`

### Assets

Shared datasets, media, and example support files.

- [Shared Data](https://github.com/openai/openai-cookbook/tree/main/examples/data): fixtures · Reusable datasets, corpora, and sample media used across many examples. · `examples/data`

### Other components

- **Cookbook**: content repo · Repository root that publishes runnable OpenAI examples and guides.
- **External APIs**: service boundary · OpenAI API plus vector DBs, cloud functions, search engines, and other example-specific services.
- **Cookbook Site**: website · Public website surface built from repository content and metadata.

## Connections

- Cookbook → Articles: contains · Repository includes long-form guides and articles.
- Cookbook → Examples: contains · Repository includes the main examples corpus.
- Cookbook → Registry: declares · Repository root registry enumerates publishable content.
- Cookbook → Contrib flow: governs · Contributor workflow and templates shape content submissions.
- Registry → Schemas: validated by · Registry and author metadata are checked against schemas.
- Notebook CI → Schemas: checks · CI validates notebook and metadata structure.
- Site Build → Cookbook Site: publishes · Build workflow produces the cookbook website.
- Articles → Cookbook Site: surfaced on · Articles are published to the public site.
- Examples → Cookbook Site: surfaced on · Examples are transformed into site content.
- Examples → Notebooks: dominates · Most example content is notebook-based.
- Examples → MDX/MD: includes · Some example content is authored as markdown guides.
- Examples → Shared Data: uses · Examples reuse packaged datasets and media fixtures.
- Examples → Shared Utils: uses · A small shared utility layer supports multiple examples.
- Examples → Vector DBs: contains · A major family of retrieval and vector database examples.
- Examples → Evals Suite: contains · Separate evaluation-oriented subsystem for benchmarking and reporting.
- Examples → Agent Systems: contains · Agent SDK and MCP examples demonstrate coordinated agent systems.
- Examples → Voice Solutions: contains · Voice and realtime speech experiences live here.
- Examples → Partner Demos: contains · Partner-integrated solution patterns form another example family.
- Examples → External APIs: integrates with · Examples independently wire OpenAI and external infrastructure.
- Evals Suite → External APIs: measures · Evals harnesses exercise model and runtime behavior through APIs.
- Agent Systems → External APIs: depends on · Agent patterns rely on OpenAI, MCP servers, and tool backends.
- Voice Solutions → External APIs: streams to · Realtime voice examples connect to speech and translation services.
- Partner Demos → External APIs: bridges · Partner demos connect to cloud, search, and SaaS systems.
