# stanford-mast/blast architecture

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

- Interactive diagram: https://gitdiagram.com/stanford-mast/blast
- Repository: https://github.com/stanford-mast/blast

## Overview

##### Project type and purpose
- From the README and file structure, this is a full-stack project whose core is a Python-based “BLAST” engine that exposes an OpenAI-compatible API for web-browsing AI.
- It includes:
- A Python package (blastai/) with modules for serving, execution, caching, scheduling, and resource management.
- A React/Next.js “blastai/frontend” application that provides a browser-based UI for interactive use.
- A separate “website” Next.js project for marketing/documentation.
- Examples, Docs, and CI configuration to support development and deployment.

##### File structure
Top-level directories:
- .github—CI/CD workflows (e.g. nextjs.yml).
- blastai—core Python package.
– cli.py, server.py, engine.py, executor.py, planner.py, scheduler.py, resource_manager.py, cache.py, config.py, secrets.py, logging_setup.py, response.py, tools.py, utils.py.
– blastai/frontend—a Next.js UI bundled into the Python package for optional local UI serving.
- docs—documentation source (MDX + assets).
- examples—sample Python scripts demonstrating usage of the blastai API.
- website—a standalone Next.js site (marketing, docs link, blog, etc.).
- pyproject.toml—package metadata and dependencies.

##### README for additional insights
- BLAST is described as a “high-performance serving engine for web browsing AI,” drop-in replacement for OpenAI’s API, with caching, parallelism, streaming, and concurrency.
- Quick-start shows Python client (OpenAI SDK) pointing at http://127.0.0.1:8000 to consume the API.

##### Main components and their interactions
a. Clients:
- CLI (blastai serve)
- Python/OpenAI SDK clients
- React/Next.js frontend
b. API Server (blastai/server.py)
- Exposes HTTP endpoints (“/v1/responses”, etc.)
- Handles authentication/secrets, config loading.
c. Engine (blastai/engine.py)
- Core orchestration for requests, applies caching logic.
d. Planner (blastai/planner.py)
- Breaks incoming prompts into tasks.
e. Scheduler (blastai/scheduler.py) + Resource Manager (blastai/resource_manager.py)
- Allocates CPU/IO resources, parallelizes tasks across workers.
f. Executor (blastai/executor.py)
- Drives browser automation (e.g. headless browser), invokes LLM calls to external API or local model.
g. Cache (blastai/cache.py)
- Caches past prefixes/responses to reduce external calls.
h. Tools (blastai/tools.py)
- Encapsulates browser‐specific or other “tool” interfaces.
i. Logging (blastai/logging_setup.py) and Utils (blastai/utils.py)
j. Frontend UI (blastai/frontend/)
- Next.js app that interacts with the API via fetch/websockets for streaming.
k. Website (website/)
- Separate Next.js app purely for marketing/documentation.
l. External Services:
- OpenAI (or other LLM)
- Headless browser environments (Playwright/Puppeteer)

##### Architectural patterns and design principles
- Layered architecture: API layer → Orchestration (Engine/Planner) → Scheduling/Resource management → Execution → External backends (LLM + browser).
- Hexagonal/“ports and adapters” flavor: Modules interact via well-defined interfaces (cache adapter, tool adapter, resource adapter).
- Concurrency and streaming: event-driven, non-blocking IO for real-time streaming.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Clients Layer
    subgraph "Clients"
        direction TB
        CLI["CLI Interface\n(blastai/cli.py)"]:::ui
        SDK["Python/OpenAI SDK Client"]:::external
        FE_UI["Bundled Frontend UI\n(blastai/frontend/)"]:::ui
    end

    %% Backend Service Layer
    subgraph "Backend Service (Python)"
        direction TB

        HTTP["API Server (HTTP Endpoints)\n(blastai/server.py)"]:::corePython

        subgraph "Core Orchestration"
            direction TB
            Engine["Core Orchestration Engine\n(blastai/engine.py)"]:::corePython
        end

        subgraph "Concurrency Engine" 
            direction TB
            Planner["Planner (Task Decomposition)\n(blastai/planner.py)"]:::corePython
            Scheduler["Scheduler (Task Scheduling)\n(blastai/scheduler.py)"]:::corePython
            ResourceMgr["Resource Manager\n(blastai/resource_manager.py)"]:::concurrency
            Executor["Executor (Browser Automation & LLM Calls)\n(blastai/executor.py)"]:::corePython
        end

        Cache["Cache Layer\n(blastai/cache.py)"]:::cache
        Tools["Tools Adapter Layer\n(blastai/tools.py)"]:::corePython

        subgraph "Config & Observability"
            direction TB
            Config["Configuration Management\n(blastai/config.py)"]:::config
            Secrets["Secrets Management\n(blastai/secrets.py)"]:::config
            Logging["Logging Setup\n(blastai/logging_setup.py)"]:::config
            Utils["Utility Functions\n(blastai/utils.py)"]:::corePython
        end
    end

    %% External Services
    subgraph "External Services"
        direction TB
        LLM["OpenAI API"]:::external
        Browser["Headless Browser Environment"]:::external
    end

    %% Data Flow
    CLI -->|HTTP/JSON| HTTP
    SDK -->|HTTP/JSON| HTTP
    FE_UI -->|Fetch/WebSocket| HTTP

    HTTP -->|Invokes| Engine
    Engine -->|Check/Store| Cache
    Engine -->|Decompose| Planner
    Planner -->|Queue Tasks| Scheduler
    Scheduler -->|Allocate| ResourceMgr
    ResourceMgr -->|Execute| Executor

    Executor -->|LLM Calls| LLM
    Executor -->|Browser Automation| Browser

    LLM -->|Response Stream| Executor
    Browser -->|Data Stream| Executor
    Executor -->|Stream Back| HTTP
    HTTP -->|Response| CLI
    HTTP -->|Response| SDK
    HTTP -->|Streaming| FE_UI

    %% Click Events
    click CLI "https://github.com/stanford-mast/blast/blob/main/blastai/cli.py"
    click HTTP "https://github.com/stanford-mast/blast/blob/main/blastai/server.py"
    click Engine "https://github.com/stanford-mast/blast/blob/main/blastai/engine.py"
    click Planner "https://github.com/stanford-mast/blast/blob/main/blastai/planner.py"
    click Scheduler "https://github.com/stanford-mast/blast/blob/main/blastai/scheduler.py"
    click ResourceMgr "https://github.com/stanford-mast/blast/blob/main/blastai/resource_manager.py"
    click Executor "https://github.com/stanford-mast/blast/blob/main/blastai/executor.py"
    click Cache "https://github.com/stanford-mast/blast/blob/main/blastai/cache.py"
    click Tools "https://github.com/stanford-mast/blast/blob/main/blastai/tools.py"
    click Config "https://github.com/stanford-mast/blast/blob/main/blastai/config.py"
    click Secrets "https://github.com/stanford-mast/blast/blob/main/blastai/secrets.py"
    click Logging "https://github.com/stanford-mast/blast/blob/main/blastai/logging_setup.py"
    click Utils "https://github.com/stanford-mast/blast/blob/main/blastai/utils.py"
    click FE_UI "https://github.com/stanford-mast/blast/tree/main/blastai/frontend/"
    
    %% Styles
    classDef corePython fill:#D0E6FF, stroke:#0366d6
    classDef ui fill:#E6FFEA, stroke:#028a0f
    classDef external fill:#FFF0B3, stroke:#d4a017
    classDef cache fill:#FFE6E6, stroke:#d63d1a
    classDef config fill:#F0F0F0, stroke:#888
    classDef concurrency fill:#E8E8FF, stroke:#5a00ff
```
