# andrewnguonly/lumos architecture

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

- Interactive diagram: https://gitdiagram.com/andrewnguonly/lumos
- Repository: https://github.com/andrewnguonly/lumos

## Overview

##### Project Type & Purpose
- This is a Chrome extension that acts as a RAG (Retrieval Augmented Generation) LLM co-pilot for web browsing.
- It relies on a local LLM (powered via Ollama) to provide inference and embedding capabilities.
- The extension integrates chat features, content parsing (with customizable configs), multimodal file processing, and tool invocation (like a calculator).

##### File Structure
- Top-level files & folders include configuration files (.eslintrc, manifest.json, tsconfig.json, webpack.config.js), documentation (docs/), tests (__tests__/), assets (screenshots, src/assets), and source code (src/).
- The src folder houses:
- The entry point (index.tsx) and primary React component (App.tsx), with various subdirectories for components (ChatBar, ChatHistory, CodeBlock), contexts (ThemeContext), pages (Popup, Options), document loaders, tools, and local vector stores.
- Scripts such as background.ts and content.ts that likely serve as the background script and content script for the Chrome extension.
- The presence of a manifest.json confirms it is a Chrome extension, while options.tsx and popup.tsx define its UI pages.

##### Key Architectural Components
- Chrome Extension Components:
- Manifest: Acts as the entry to define the extension’s permissions and entry points.
- Background Script (src/scripts/background.ts): Runs as a long-lived process handling events and managing communications.
- Content Script (src/scripts/content.ts): Interacts with the current webpage, possibly for content parsing and multimodal support.
- UI Components: Popup (src/pages/Popup.tsx) and Options (src/pages/Options.tsx) pages along with various React components (ChatBar, ChatHistory, CodeBlock).
- Contexts (src/contexts/ThemeContext.tsx): Providing application-wide shared state (e.g., light/dark theme).

- Local LLM Integration:
- The extension communicates with a locally running Ollama server (as detailed in the README). This server handles:
- LLM inference.
- Embedding model inference.
- Possibly vectorstore operations (src/vectorstores/enhanced_memory.ts).

- RAG Pipeline:
- Document Loaders (src/document_loaders/): Modules like csv.ts and dynamic_file.ts prepare input text (or files such as CSV) for the LLM.
- Content Parser & Config (src/contentConfig.ts): Customizable per-URL behavior (see docs/content_parser.md) that feeds data into the RAG vectorstore.
- Tools (src/tools/calculator.ts): Additional helpers that process specific prompt types.

- External Integrations & Workflows:
- The detailed README explains support for file attachments, multimodal processing (image handling in docs/multimodal.md), and third-party guidance (e.g., LangChain).

##### Relationships and Interactions
- UI Components (Popup, Options) → communicate user actions (prompt, configuration changes).
- Data/process flows from the content script and background script → to external calls made to the local Ollama server.
- Responses (LLM-generated answers, embeddings, and tool responses) flow back into the extension’s UI.
- The vector store (enhanced_memory.ts) is used as part of the retrieval pipeline when handling long documents or summarizations.
- The document loaders feed parsed content into the RAG process.

- Asynchronous, event-driven design common to Chrome extensions, where the background and content scripts manage state and relay messages between the UI and the local server.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Chrome Extension Layer
    subgraph "Chrome Extension"
        direction TB
        Manifest["Chrome Extension Manifest"]:::extension
        BG["Background Script"]:::script
        CS["Content Script"]:::script
        subgraph "UI Components"
            direction TB
            Popup["Popup UI"]:::ui
            Options["Options UI"]:::ui
            Entry["Entry Point: index.tsx"]:::ui
            App["Primary React App (App.tsx)"]:::ui
            ChatBar["ChatBar"]:::ui
            ChatHistory["ChatHistory"]:::ui
            CodeBlock["CodeBlock"]:::ui
            Theme["Theme Context"]:::ui
        end
    end

    %% Local LLM & RAG Pipeline Layer
    subgraph "Local LLM & RAG Pipeline"
        direction TB
        Ollama["Ollama Server"]:::server
        subgraph "Local LLM Integration"
            direction TB
            LLM["LLM Inference"]:::server
            Embedding["Embedding Generation"]:::server
            Vector["Vector Store"]:::server
        end
        DocumentLoaders["Document Loaders"]:::rag
        ContentParser["Content Parser Config"]:::rag
        Calculator["Calculator Tool"]:::rag
    end

    %% Connections: UI to Background
    Popup -->|"user_request"| BG
    Options -->|"user_request"| BG

    %% Connections: Background and Content Scripts to Local Server
    BG -->|"server_request"| Ollama
    CS -->|"server_request"| Ollama
    Ollama -->|"server_response"| BG

    %% Connections: RAG Pipeline feeding into Local LLM
    DocumentLoaders -->|"parsed_docs"| Ollama
    ContentParser -->|"config_data"| Ollama
    Calculator -->|"tool_invocation"| Ollama

    %% Styling
    classDef extension fill:#f4cccc,stroke:#b22222,stroke-width:2px;
    classDef script fill:#c9daf8,stroke:#1155cc,stroke-width:2px;
    classDef ui fill:#ffe599,stroke:#b45f06,stroke-width:2px;
    classDef server fill:#d9ead3,stroke:#38761d,stroke-width:2px;
    classDef rag fill:#d0e0e3,stroke:#2e5c6e,stroke-width:2px;

    %% Click Events
    click Manifest "https://github.com/andrewnguonly/lumos/blob/main/manifest.json"
    click BG "https://github.com/andrewnguonly/lumos/blob/main/src/scripts/background.ts"
    click CS "https://github.com/andrewnguonly/lumos/blob/main/src/scripts/content.ts"
    click Popup "https://github.com/andrewnguonly/lumos/blob/main/src/pages/Popup.tsx"
    click Options "https://github.com/andrewnguonly/lumos/blob/main/src/pages/Options.tsx"
    click Entry "https://github.com/andrewnguonly/lumos/blob/main/src/index.tsx"
    click App "https://github.com/andrewnguonly/lumos/blob/main/src/App.tsx"
    click ChatBar "https://github.com/andrewnguonly/lumos/blob/main/src/components/ChatBar.tsx"
    click ChatHistory "https://github.com/andrewnguonly/lumos/blob/main/src/components/ChatHistory.tsx"
    click CodeBlock "https://github.com/andrewnguonly/lumos/blob/main/src/components/CodeBlock.tsx"
    click Theme "https://github.com/andrewnguonly/lumos/blob/main/src/contexts/ThemeContext.tsx"
    click ContentParser "https://github.com/andrewnguonly/lumos/blob/main/src/contentConfig.ts"
    click DocumentLoaders "https://github.com/andrewnguonly/lumos/tree/main/src/document_loaders/"
    click Calculator "https://github.com/andrewnguonly/lumos/blob/main/src/tools/calculator.ts"
    click Vector "https://github.com/andrewnguonly/lumos/blob/main/src/vectorstores/enhanced_memory.ts"
    
    %% Additional Click Events for Associated CSS Files
    click Popup "https://github.com/andrewnguonly/lumos/blob/main/src/pages/Popup.css"
    click Options "https://github.com/andrewnguonly/lumos/blob/main/src/pages/Options.css"
    click ChatBar "https://github.com/andrewnguonly/lumos/blob/main/src/components/ChatBar.css"
```
