# bracesproul/site-rag architecture

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

- Interactive diagram: https://gitdiagram.com/bracesproul/site-rag
- Repository: https://github.com/bracesproul/site-rag

## Overview

##### Project Type and Purpose
- Site RAG is a Chrome extension built as a full-stack, client-side application. It provides an interactive chat UI allowing users to query the current webpage or entire site, performs retrieval-augmented generation (RAG) or context-stuffing with local or remote vector stores, and runs 100% in the browser (optionally integrating Supabase or a local Ollama LLM).

##### Architectural Overview
At a high level, the extension consists of:
a. A React+TypeScript frontend (popup UI)
b. A set of service libraries handling storage, indexing, API integrations, and query generation
c. External dependencies: LLM providers (OpenAI, Anthropic, Google, etc.), FireCrawl scraper API, and optionally Supabase (vector store)

##### Main Components
- UI Layer
- Popup UI (src/index.html, src/index.tsx, src/App.tsx)
- ChatView, SettingsForm, model-selector, index-site dialogs
- Reusable UI primitives (src/components/ui/*) and assistant-ui (thread, markdown, syntax highlighting)
- State & Storage
- store.ts: central state management (in-memory + persisted to browser storage)
- clear-docs.ts, last-indexed.ts: helper modules for session/document lifecycle
- index-db.ts: IndexedDB wrapper for local document storage
- Query & RAG Logic
- graphs/query: prompt generation, multi-query mode, utility functions
- constants.ts, types.ts: model/provider definitions, type safety
- API Integrations
- supabase.ts: client for remote vector store (PostgreSQL + pgvector)
- utils.ts: wrappers for fetch calls, FireCrawl scraper integration
- Runtime Glue
- runtimes/assistant-ui.tsx: bootstraps the React popup in extension context
- Build & Config
- Vite (vite.config.ts), TypeScript (tsconfig.json), PostCSS/Tailwind, ESLint, Jest

##### Component Interactions & Data Flow
1. User opens extension popup → React App mounts via runtimes/assistant-ui.tsx
2. SettingsForm reads/writes API keys and configuration into browser storage (store.ts)
3. User initiates a query in ChatView
- If “context stuffing” mode: src/lib/utils scrapes current page via FireCrawl
- If “RAG” mode:
a. graphs/query/generate-queries.ts generates semantic queries
b. Either index-db (local IndexedDB) or supabase.ts (remote DB) returns nearest documents
- Graphs utilities return a consolidated prompt
4. The prompt is sent to the chosen LLM provider (OpenAI, Anthropic, Google GenAI, local Ollama) via initChatModel wrapper
5. Model response flows back into ChatView and is rendered via assistant-ui components
6. Retrieved documents and session metadata are stored for follow-up queries (sessionID management)

##### Architectural Patterns & Principles
- Separation of Concerns: UI components ↔ business logic (graphs and lib) ↔ storage ↔ external services
- Modular Design: each service (scraper, vector store, LLM) is encapsulated in its own module
- Single Page UI: reactive React app loaded once by the extension
- Client-side Persistence: browser storage + IndexedDB for offline capability

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Global actor
    User["User"]:::external

    %% Frontend Layer
    subgraph "Frontend (React+TS)"
        direction TB
        PopupUI["Popup UI<br/>(React+TS)"]:::frontend
        SettingsForm["SettingsForm"]:::frontend
        ChatView["ChatView"]:::frontend
        subgraph "UI Primitives"
            UIPrimitives["Reusable UI Primitives"]:::frontend
        end
        subgraph "Assistant-UI Components"
            AssistantUI["Assistant-UI Components"]:::frontend
        end
    end

    %% State & Storage Layer
    subgraph "State & Storage" 
        direction TB
        Store["store.ts"]:::storage
        ClearDocs["clear-docs.ts"]:::storage
        LastIndexed["last-indexed.ts"]:::storage
        IndexDB["index-db.ts<br/>(IndexedDB)"]:::storage
        BrowserStorage["Browser Storage"]:::storage
    end

    %% Query & RAG Logic Layer
    subgraph "Query Engine (RAG Logic)"
        direction TB
        QueryGraph["graphs/query"]:::logic
        Constants["constants.ts"]:::logic
        Types["types.ts"]:::logic
    end

    %% API Adapters Layer
    subgraph "API Adapters"
        direction TB
        FireCrawlAdapter["utils.ts<br/>(FireCrawl Scraper)"]:::logic
        SupabaseAdapter["supabase.ts<br/>(Supabase Vector Store)"]:::logic
        LLMAdapter["initChatModel Wrapper"]:::logic
    end

    %% External Services
    subgraph "External Services"
        direction TB
        FireCrawlService["FireCrawl API"]:::external
        SupabaseService["Supabase (PostgreSQL + pgvector)"]:::external
        LLMProviders["LLM Providers<br/>(OpenAI, Anthropic, Google GenAI, Ollama)"]:::external
    end

    %% Connections
    User -->|opens popup| PopupUI
    PopupUI -->|"mount via runtimes/assistant-ui.tsx"| PopupUI
    PopupUI --> SettingsForm
    PopupUI --> ChatView
    SettingsForm -->|reads/writes config| Store
    Store <--> BrowserStorage
    ChatView -->|initiates query| QueryGraph
    QueryGraph -->|reads session/docs| Store
    QueryGraph -->|reads/writes docs| IndexDB
    QueryGraph -->|fetch remote docs| SupabaseAdapter
    QueryGraph -->|scrape page| FireCrawlAdapter
    FireCrawlAdapter -->|fetch html| FireCrawlService
    SupabaseAdapter -->|vector search| SupabaseService
    QueryGraph -->|build prompt| LLMAdapter
    LLMAdapter -->|invoke LLM| LLMProviders
    LLMProviders -->|response| LLMAdapter
    LLMAdapter -->|response| ChatView
    ChatView -->|render via assistant-ui| AssistantUI
    ChatView -->|use primitives| UIPrimitives

    %% Click Events
    click PopupUI "https://github.com/bracesproul/site-rag/blob/main/src/index.tsx"
    click PopupUI "https://github.com/bracesproul/site-rag/blob/main/src/App.tsx"
    click PopupUI "https://github.com/bracesproul/site-rag/blob/main/src/index.html"
    click PopupUI "https://github.com/bracesproul/site-rag/blob/main/src/runtimes/assistant-ui.tsx"
    click ChatView "https://github.com/bracesproul/site-rag/blob/main/src/components/ChatView.tsx"
    click SettingsForm "https://github.com/bracesproul/site-rag/blob/main/src/components/SettingsForm.tsx"
    click modelSelector "https://github.com/bracesproul/site-rag/blob/main/src/components/model-selector/index.tsx"
    click IndexSite "https://github.com/bracesproul/site-rag/blob/main/src/components/index-site/index.tsx"
    click IndexConfirm "https://github.com/bracesproul/site-rag/blob/main/src/components/index-site/IndexConfirmDialog.tsx"
    click UIPrimitives "https://github.com/bracesproul/site-rag/tree/main/src/components/ui/"
    click AssistantUI "https://github.com/bracesproul/site-rag/tree/main/src/components/assistant-ui/"
    click Store "https://github.com/bracesproul/site-rag/blob/main/src/lib/store.ts"
    click ClearDocs "https://github.com/bracesproul/site-rag/blob/main/src/lib/clear-docs.ts"
    click LastIndexed "https://github.com/bracesproul/site-rag/blob/main/src/lib/last-indexed.ts"
    click IndexDB "https://github.com/bracesproul/site-rag/blob/main/src/lib/index-db.ts"
    click QueryGraph "https://github.com/bracesproul/site-rag/tree/main/src/graphs/query/"
    click Constants "https://github.com/bracesproul/site-rag/blob/main/src/constants.ts"
    click Types "https://github.com/bracesproul/site-rag/blob/main/src/types.ts"
    click FireCrawlAdapter "https://github.com/bracesproul/site-rag/blob/main/src/lib/utils.ts"
    click SupabaseAdapter "https://github.com/bracesproul/site-rag/blob/main/src/lib/supabase.ts"

    %% Styles
    classDef frontend fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef logic fill:#90EE90,stroke:#000,stroke-width:1px
    classDef storage fill:#FFA500,stroke:#000,stroke-width:1px
    classDef external fill:#D3D3D3,stroke:#000,stroke-width:1px
```
