# openai/model_spec architecture

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

- Interactive diagram: https://gitdiagram.com/openai/model_spec
- Repository: https://github.com/openai/model_spec

## Overview

##### Project type and purpose
- This is a static documentation site (the Model Spec) plus a corpus of evaluation‐prompt examples.
- Purpose: maintain markdown source for the spec (model_spec.md), sample evaluation prompts (examples/*.md), and publish all releases as HTML under docs/.

##### File structure
- Top‐level files
– model_spec.md (master spec source)
– examples/*.md (hundreds of prompt examples used to test model behavior)
– README.md, CHANGELOG.md, LICENSE
- docs/ directory
– docs/index.html, docs/2025-*.html (built HTML releases)
– docs/fonts/, docs/fonts.gen.css (asset files)
– docs/CNAME (custom domain for GitHub Pages)
- No traditional “src/” or “backend/”—the repository is content plus prebuilt artifacts.

##### README for extra insights
- Describes:
– Where to see the rendered spec (model-spec.openai.com)
– That docs/ contains archive of all released HTML versions
– That examples/ holds evaluation prompts tagged from the spec source
- Build tooling is not explicit but implied: a static‐site generator (SSG) or custom script transforms markdown → HTML.

##### Core components
a. Content Sources
– model_spec.md (core spec)
– examples/*.md (evaluation prompts)
b. Build Pipeline (Static Site Generator)
– Input: markdown sources
– Process: SSG or script (e.g., Jekyll, Hugo, MkDocs, or custom Node/Python script)
– Output: docs/ HTML, asset files
c. Hosting/Deployment
– docs/ directory served via GitHub Pages using CNAME → model-spec.openai.com
d. End Users
– Web browsers requesting pages & assets from model-spec.openai.com
e. External Links
– model-spec.openai.com, OpenAI Blog link (for reference, no deep integration)

##### Relationships & Data Flows
- Author commits markdown to Git repo (main branch)
↓
- CI pipeline / local build runs SSG
↓
- Generated HTML and asset files land in docs/
↓
- GitHub Pages serves docs/ as website at model-spec.openai.com
↓
- End‐users (browsers) fetch HTML, CSS, fonts

##### Architectural patterns / design principles
- Content‐centric “Content + Presentation” separation—raw markdown vs. generated HTML
- Static site generation (no server‐side code at runtime)
- Versioned artifacts: multiple releases archived under docs/
- Simple CI/CD: commit → build → deploy (GitHub Pages)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Developer Environment
    subgraph "Developer Environment"
        modelSpec["model_spec.md"]:::content
        examples["examples/"]:::content
        README["README.md"]:::metadata
        CHANGELOG["CHANGELOG.md"]:::metadata
        LICENSE["LICENSE"]:::metadata
    end

    %% Build Step
    SSG["Static Site Generator"]:::build

    %% Build Artifacts
    subgraph "Build & Artifact"
        docsHTML["docs/ (HTML pages)"]:::artifact
        docsFontsDir["docs/fonts/"]:::artifact
        docsFontsCSS["docs/fonts.gen.css"]:::artifact
        docsCNAME["docs/CNAME"]:::artifact
    end

    %% Hosting & Delivery
    subgraph "Hosting & Delivery"
        GitHubPages["GitHub Pages<br/>model-spec.openai.com"]:::hosting
        EndUser["End User (Browser)"]:::user
    end

    %% Connections
    modelSpec -->|commit & CI triggers| SSG
    examples -->|commit & CI triggers| SSG
    README -->|metadata| SSG
    CHANGELOG -->|metadata| SSG
    LICENSE -->|metadata| SSG

    SSG -->|"generates HTML pages"| docsHTML
    SSG -->|"generates assets"| docsFontsDir
    SSG -->|"generates CSS"| docsFontsCSS
    SSG -->|"creates CNAME"| docsCNAME

    docsHTML -->|"deploy to GitHub Pages"| GitHubPages
    docsFontsDir -->|"deploy to GitHub Pages"| GitHubPages
    docsFontsCSS -->|"deploy to GitHub Pages"| GitHubPages
    docsCNAME -->|"deploy to GitHub Pages"| GitHubPages

    GitHubPages -->|"HTTP GET"| EndUser

    %% Click Events
    click modelSpec "https://github.com/openai/model_spec/blob/main/model_spec.md"
    click examples "https://github.com/openai/model_spec/tree/main/examples/"
    click README "https://github.com/openai/model_spec/blob/main/README.md"
    click CHANGELOG "https://github.com/openai/model_spec/blob/main/CHANGELOG.md"
    click LICENSE "https://github.com/openai/model_spec/tree/main/LICENSE"
    click docsHTML "https://github.com/openai/model_spec/tree/main/docs/"
    click docsFontsDir "https://github.com/openai/model_spec/tree/main/docs/fonts/"
    click docsFontsCSS "https://github.com/openai/model_spec/blob/main/docs/fonts.gen.css"
    click docsCNAME "https://github.com/openai/model_spec/tree/main/docs/CNAME"

    %% Styles
    classDef content fill:#BBDEFB,stroke:#000
    classDef build fill:#FFCC80,stroke:#000
    classDef artifact fill:#C8E6C9,stroke:#000
    classDef hosting fill:#E1BEE7,stroke:#000
    classDef user fill:#F8BBD0,stroke:#000
    classDef metadata fill:#E0E0E0,stroke:#000arine
```
