# jash4305/berkshire-hathaway-rag architecture

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

- Interactive diagram: https://gitdiagram.com/jash4305/berkshire-hathaway-rag
- Repository: https://github.com/jash4305/berkshire-hathaway-rag

## Overview

##### Project Type and Purpose
- This is a full-stack Retrieval-Augmented-Generation (RAG) system for interactive Q&A over Warren Buffett’s shareholder letters.
- It consists of two main workflows:
- Ingestion Pipeline – to parse documents, generate embeddings, and store them in a vector‐enabled PostgreSQL database.
- Query/API Layer – to accept user questions via a UI, perform semantic search + LLM calls, and return answers with citations.

##### High‐Level Components
a. User Interface (Web Client)
- A browser‐based chat interface (accessed on `http://localhost:4111`).
- Streaming responses, conversation memory, and citation display.
b. API / Application Server
- A Node.js TypeScript service (entrypoint via `src/mastra/index.ts`, built & run with `npm run dev` / `npm run start`).
- Hosts HTTP endpoints for:
1. Ingestion trigger (`npm run ingest` → `src/run-ingestion.ts`).
2. Chat queries (handled by Mastra workflows).
c. Ingestion Workflow
- `src/mastra/workflows/ingestion-workflow.ts`: orchestrates reading PDF/text files, calling the Berkshire‐tool for text extraction, generating embeddings, and inserting vector records.
- Relies on `src/mastra/tools/berkshire-tool.ts`.
d. Query Workflow
- `src/mastra/workflows/weather-workflow.ts` (example of a second domain) & primary chat workflow in `src/mastra/index.ts`.
- Agents (`src/mastra/agents/*.ts`) orchestrate LLM calls + tool invocations.
e. Tools & Agents
- Tools encapsulate concrete actions:
- `berkshire-tool.ts` (loads shareholder letters, returns chunks).
- `weather-tool.ts` (retrieves live weather data).
- Agents implement chain logic: call the LLM, decide on tool invocation, and parse results.
f. Vector Store (PostgreSQL + pgvector)
- Database schema defined in `src/database/schema.sql`.
- `src/mastra/vectors/postgres-vector.ts` wraps vector insert/search.
g. External Services
- OpenAI API for embeddings & GPT-4o calls.
- PostgreSQL for persistent vector storage.

##### Relationships and Data Flows
- Ingestion flow (one‐time):
User or CI → `run-ingestion.ts` → Ingestion Workflow → Berkshire‐tool → Text chunks → OpenAI Embeddings API → Postgres Vector Store
- Query/chat flow:
Web Client → HTTP API endpoint in `index.ts` → Query Workflow/Agent →
- Vector Store (semantic search)
- OpenAI Chat API →
→ Query Workflow aggregates results with citations → API returns streamed chat to Web Client

##### Architectural Patterns & Design Principles
- RAG (Retrieval before Generation)
- Separation of concerns:
- Ingestion vs. Query pipelines
- Agents vs. Tools vs. Vector store wrapper
- Modular design using Mastra framework for workflows & agents

##### Technologies & Frameworks to Call Out
- TypeScript / Node.js
- Mastra (workflow/agent orchestration)
- OpenAI (GPT-4o & Embeddings)
- PostgreSQL + pgvector
- NPM scripts as “infrastructure as code” for setup & execution

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client (Browser UI)" 
        direction TB
        WebClient["Browser UI<br/>(http://localhost:4111)"]:::component
    end

    %% Backend Layer
    subgraph "Backend"
        direction TB

        subgraph "Scripts & Configuration"
            direction TB
            package["package.json"]:::component
            EnvSample[".env.sample"]:::component
            runIngest["Ingestion Trigger Script<br/>(npm run ingest)"]:::script
        end

        subgraph "API Server"
            direction TB
            Index["API Entrypoint<br/>(src/mastra/index.ts)"]:::component
        end

        subgraph "Mastra Engine"
            direction TB

            subgraph "Workflows"
                direction TB
                IngestWF["Ingestion Workflow"]:::workflow
                WeatherWF["Query Workflow (Weather)"]:::workflow
            end

            subgraph "Tools"
                direction TB
                BerkshireTool["Berkshire Tool"]:::component
                WeatherTool["Weather Tool"]:::component
            end

            subgraph "Agents"
                direction TB
                BerkshireAgent["Berkshire Agent"]:::component
                WeatherAgent["Weather Agent"]:::component
            end

            VectorWrapper["Postgres Vector Wrapper"]:::component
        end
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        Postgres[(PostgreSQL + pgvector)]:::datastore
        Schema["schema.sql"]:::datastore
    end

    %% External Services
    subgraph "External Services"
        direction TB
        OpenAIEmbeddings((OpenAI Embeddings API)):::external
        OpenAIChat((OpenAI Chat API)):::external
    end

    %% Relationships - Ingestion Flow
    WebClient -->|triggers| runIngest
    package -->|defines scripts| runIngest
    runIngest -->|calls| IngestWF
    IngestWF -->|uses| BerkshireTool
    BerkshireTool -->|embeddings| OpenAIEmbeddings
    OpenAIEmbeddings -->|stores vectors| VectorWrapper
    VectorWrapper -->|writes| Postgres
    Schema -->|defines schema| Postgres

    %% Relationships - Query Flow
    WebClient -->|HTTP request| Index
    Index -->|invokes| BerkshireAgent
    BerkshireAgent -->|semantic search| VectorWrapper
    VectorWrapper -->|reads| Postgres
    BerkshireAgent -->|LLM call| OpenAIChat
    OpenAIChat -->|response| BerkshireAgent
    BerkshireAgent -->|streams| Index
    Index -->|streams| WebClient

    %% Weather Example Flow
    Index -->|example query| WeatherWF
    WeatherWF -->|orchestrates| WeatherAgent
    WeatherAgent -->|calls tool| WeatherTool
    WeatherTool -->|fetches data| OpenAIChat
    OpenAIChat -->|response| WeatherAgent
    WeatherAgent -->|returns| Index

    %% Click Events
    click Index "https://github.com/jash4305/berkshire-hathaway-rag/blob/main/src/mastra/index.ts"
    click runIngest "https://github.com/jash4305/berkshire-hathaway-rag/blob/main/src/run-ingestion.ts"
    click IngestWF "https://github.com/jash4305/berkshire-hathaway-rag/blob/main/src/mastra/workflows/ingestion-workflow.ts"
    click WeatherWF "https://github.com/jash4305/berkshire-hathaway-rag/blob/main/src/mastra/workflows/weather-workflow.ts"
    click BerkshireTool "https://github.com/jash4305/berkshire-hathaway-rag/blob/main/src/mastra/tools/berkshire-tool.ts"
    click WeatherTool "https://github.com/jash4305/berkshire-hathaway-rag/blob/main/src/mastra/tools/weather-tool.ts"
    click BerkshireAgent "https://github.com/jash4305/berkshire-hathaway-rag/blob/main/src/mastra/agents/berkshire-agent.ts"
    click WeatherAgent "https://github.com/jash4305/berkshire-hathaway-rag/blob/main/src/mastra/agents/weather-agent.ts"
    click VectorWrapper "https://github.com/jash4305/berkshire-hathaway-rag/blob/main/src/mastra/vectors/postgres-vector.ts"
    click Schema "https://github.com/jash4305/berkshire-hathaway-rag/blob/main/src/database/schema.sql"
    click package "https://github.com/jash4305/berkshire-hathaway-rag/blob/main/package.json"
    click EnvSample "https://github.com/jash4305/berkshire-hathaway-rag/blob/main/.env.sample"

    %% Styles
    classDef component fill:#aecbf0,stroke:#333,stroke-width:1px
    classDef script fill:#f5c098,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5
    classDef workflow fill:#f5c098,stroke:#333,stroke-width:1px
    classDef datastore fill:#9ae69a,stroke:#333,stroke-width:1px
    classDef external fill:#d3d3d3,stroke:#333,stroke-width:1px
```
