# openai/build-hours architecture

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

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

## Overview

##### Project type and purpose
- This repo is a “monorepo” of small, self-contained demo applications (numbered 10–13, 2–9, etc.) showcasing different OpenAI API use-cases (e.g., distillation notebooks, recommendation engine, agentic tool calling, image generation, fine-tuning examples, real-time demos, etc.).
- Each numbered directory is effectively its own mini-project (some in Python, some in Next.js/React, some pure scripts/notebooks).

##### File structure
- Top-level: .gitignore, LICENSE, README.md, then dozens of numbered subdirectories (10-distillation, 11-recommendation, …, 13-image-gen, 2-assistants, …).
- Each subdirectory generally has its own source code, configuration, requirements/package files, and sometimes a docker-compose or notebook.
- Patterns:
- Python demos: app.py, helper_functions.py, config.py, Docker compose + Qdrant or SQLite.
- Next.js demos: `imagegen-demo` with `src/app/api/*` routes, React components, Tailwind.
- Jupyter notebooks for research purposes.
- Utilities and scripts for ingest/upload, evaluation, fine-tuning.

##### README
- The top-level README introduces “Build Hours”: monthly events for startups and developers to explore OpenAI’s API.
- No single architectural overview is provided—each subfolder is a standalone exercise.

##### Detail without overthinking
- At the monorepo level: group each numbered example as its own “module” node, showing that it has its own tech stack.
- At the demo level: drill into one representative folder and break it into UI, service, data, external API.
- Moving parts: local code, containers, scripts, external APIs.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Monorepo Overview
    subgraph "Build Hours Monorepo"
        subgraph "Infrastructure"
            Dev["Developer Environment"]:::external
            CI["CI/CD Pipeline"]:::external
            PM["Package Manager (pip / npm)"]:::external
            DH["Docker Host"]:::external
        end
        subgraph "Demo Modules"
            Rec["11-recommendation"]:::module
            IMG["13-image-gen"]:::module
            AGT["12-agentic-tool-calling"]:::module
            DST["10-distillation"]:::module
            STR["6-structured_outputs_assistant-final"]:::module
            RT["9-realtime-console-example"]:::module
            SP["7-shipmentPlanning"]:::module
            FT["3-4o_mini_fine_tuning"]:::module
        end
    end

    %% Detailed 11-recommendation Architecture
    subgraph "11-recommendation Detailed Architecture"
        UI["Streamlit UI Pages"]:::ui
        BE["Backend Service Logic"]:::service
        CFG["Configuration Layer"]:::service
        DB["Qdrant Vector DB"]:::data
        SCRIPT["Data Ingestion Script"]:::service
        DATA["Sample Data (CSV)"]:::data
        API["OpenAI Embedding API"]:::external
        Docker["Docker Compose Orchestration"]:::service
    end

    %% Relationships
    Dev --> Rec
    PM --> Rec
    DH --> Rec
    CI --> Rec

    Rec -->|"contains"| UI
    Rec -->|"contains"| BE
    Rec -->|"contains"| CFG
    Rec -->|"contains"| DB
    Rec -->|"contains"| SCRIPT
    Rec -->|"contains"| DATA
    Rec -->|"contains"| Docker

    UI -->|"requests"| BE
    BE -->|"queries"| DB
    BE -->|"calls"| API
    SCRIPT -->|"loads data into"| DB
    SCRIPT -->|"reads"| DATA
    Docker -->|"orchestrates"| BE
    Docker -->|"orchestrates"| DB

    %% Click Events for 11-recommendation
    click Rec "https://github.com/openai/build-hours/tree/main/11-recommendation"
    click UI "https://github.com/openai/build-hours/blob/main/11-recommendation/pages/page_1_semantic_search.py"
    click UI "https://github.com/openai/build-hours/blob/main/11-recommendation/pages/page_2_explainable_recommendations.py"
    click BE "https://github.com/openai/build-hours/blob/main/11-recommendation/app.py"
    click BE "https://github.com/openai/build-hours/blob/main/11-recommendation/helper_functions.py"
    click CFG "https://github.com/openai/build-hours/blob/main/11-recommendation/config.py"
    click SCRIPT "https://github.com/openai/build-hours/blob/main/11-recommendation/upload-to-qdrant.py"
    click DATA "https://github.com/openai/build-hours/blob/main/11-recommendation/upload-data/fake_hardware_data.csv"
    click Docker "https://github.com/openai/build-hours/blob/main/11-recommendation/docker-compose.yaml"
    click CFG "https://github.com/openai/build-hours/blob/main/11-recommendation/requirements.txt"

    %% Click Events for other demo modules
    click IMG "https://github.com/openai/build-hours/tree/main/13-image-gen/imagegen-demo"
    click AGT "https://github.com/openai/build-hours/tree/main/12-agentic-tool-calling"
    click DST "https://github.com/openai/build-hours/tree/main/10-distillation"
    click STR "https://github.com/openai/build-hours/tree/main/6-structured_outputs-assistant-final"
    click RT "https://github.com/openai/build-hours/tree/main/9-realtime/openai-realtime-console-example"
    click SP "https://github.com/openai/build-hours/tree/main/7-reasoning/shipmentPlanning"
    click FT "https://github.com/openai/build-hours/tree/main/3-4o_mini_fine_tuning"

    %% Styling
    classDef ui fill:#cce5ff,stroke:#0366d6,color:#000
    classDef service fill:#d4edda,stroke:#237a1d,color:#000
    classDef data fill:#fff3cd,stroke:#856404,color:#000
    classDef external fill:#e2e3e5,stroke:#6c757d,color:#000
    classDef module fill:#f0f0f0,stroke:#343a40,color:#000
```
