# harveyai/deep-research-starter architecture

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

- Interactive diagram: https://gitdiagram.com/harveyai/deep-research-starter
- Repository: https://github.com/harveyai/deep-research-starter

## Overview

##### Project type and purpose
- This is a lightweight single-page “full-stack” style demo application built in Python using Streamlit.
- Purpose: provide an interactive UI for sending prompts to the OpenAI Deep Research API, streaming back events, and displaying them in real time.
- It also ships sample output files (JSONL and Pydantic representations) for offline inspection.

##### File structure
- Top level:
- streamlit_app.py – the main application entrypoint
- pyproject.toml – Python dependency and metadata config
- assets/ – UI static assets (e.g., the screenshot)
- output_samples/ – recorded API output for reference
- README.md, LICENSE, .gitignore, .python-version
- No separate “backend” directory: the Streamlit runtime both serves the UI and performs API calls.
- No microservices; the only external dependency at runtime is the OpenAI Deep Research API.

##### README for additional insights
- It confirms use of Streamlit (`streamlit run streamlit_app.py`) and the Deep Research API.
- Mentions Pydantic for modeling the streamed events (implied by the Python repr sample).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Layer
    subgraph "Local Client"
        Browser["User Browser"]:::user
    end

    %% Application Layer
    subgraph "Streamlit Application"
        Streamlit["Streamlit App\n(streamlit_app.py)"]:::app
        Pydantic["Pydantic Models"]:::parser
    end

    %% Static Assets and Sample Outputs
    subgraph "Local Filesystem"
        Assets["Static Assets\n(assets/)"]:::assets
        Samples["Sample Outputs\n(output_samples/)"]:::storage
        Events["events_jsonl.jsonl"]:::file
        Repr["events_python_repr.txt"]:::file
    end

    %% External API
    API["OpenAI Deep Research API"]:::external

    %% Project Configuration & Docs
    subgraph "Project Files"
        PyProj["pyproject.toml"]:::file
        Readme["README.md"]:::file
        License["LICENSE"]:::file
        Gitignore[".gitignore"]:::file
        PyVer[".python-version"]:::file
    end

    %% Data Flows
    Browser -->|"User Input"| Streamlit
    Streamlit -->|"Streaming Request"| API
    API -->|"Streamed JSONL"| Streamlit
    Streamlit -->|"Parse Events"| Pydantic
    Pydantic -->|"Render Updates"| Streamlit
    Streamlit -->|"UI Updates"| Browser
    Streamlit -->|"Load Assets"| Assets
    Streamlit -->|"Write Samples"| Samples

    %% Detail Outputs
    Samples --> Events
    Samples --> Repr

    %% Click Events
    click Streamlit "https://github.com/harveyai/deep-research-starter/blob/main/streamlit_app.py"
    click Assets "https://github.com/harveyai/deep-research-starter/tree/main/assets/"
    click Samples "https://github.com/harveyai/deep-research-starter/tree/main/output_samples/"
    click Events "https://github.com/harveyai/deep-research-starter/blob/main/output_samples/events_jsonl.jsonl"
    click Repr "https://github.com/harveyai/deep-research-starter/blob/main/output_samples/events_python_repr.txt"
    click PyProj "https://github.com/harveyai/deep-research-starter/blob/main/pyproject.toml"
    click Readme "https://github.com/harveyai/deep-research-starter/blob/main/README.md"
    click License "https://github.com/harveyai/deep-research-starter/tree/main/LICENSE"
    click Gitignore "https://github.com/harveyai/deep-research-starter/blob/main/.gitignore"
    click PyVer "https://github.com/harveyai/deep-research-starter/blob/main/.python-version"

    %% Styles
    classDef user fill:#D0E8FF,stroke:#005BBB,color:#005BBB
    classDef app fill:#E0FFE0,stroke:#009900,color:#006600
    classDef external fill:#FFE0E0,stroke:#CC0000,color:#800000
    classDef assets fill:#FFF8DC,stroke:#DAA520,color:#8B4513
    classDef storage fill:#E0FFE0,stroke:#00AA00,color:#006600
    classDef parser fill:#E8F0FF,stroke:#3366CC,color:#000099
    classDef file fill:#F0F0F0,stroke:#CCCCCC,color:#666666
```
