# prithwin55/insightanywhere architecture

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

- Interactive diagram: https://gitdiagram.com/prithwin55/insightanywhere
- Repository: https://github.com/prithwin55/insightanywhere

## Overview

1. **High-level shape**  
   The repo is split into two major runtime parts: a **Chrome extension** for user interaction and page capture, and a **Python AI backend** that performs retrieval-augmented answering. The design is intentionally stateless: each query is handled against the currently viewed page/video context without long-term storage.

2. **Chrome extension UI layer**  
   The `chrome-extension/` folder contains the user-facing surface:
   - `popup.html`, `popup.js`, and `styles.css` implement the lightweight chat UI shown in the browser.
   - `manifest.json` defines the extension entry points and permissions.
   This layer is responsible for collecting the user’s question and displaying answers, not for doing the AI work itself.

3. **Extension orchestration layer**  
   `chrome-extension/background.js` is the likely bridge between the popup and the current tab. In an architecture diagram, treat it as the coordination point that can:
   - inspect the active page,
   - capture page/YouTube context,
   - forward the query plus context to the backend,
   - return the generated answer to the popup.

4. **Page and video context extraction**  
   The product supports two context sources:
   - **regular webpages**, where readable page text is extracted,
   - **YouTube pages**, where title/description and optionally transcript data are used.
   This context capture happens close to the browser runtime so the backend receives only the relevant content for the current tab.

5. **Python backend boundary**  
   `server.py` is the backend entry point and likely exposes an HTTP API used by the extension. It is the boundary between browser-side context collection and the AI pipeline. The extension should be viewed as a client of this service.

6. **Retrieval-Augmented Generation pipeline**  
   The README describes the core backend behavior: the input page/video content is processed per request, then split into chunks, embedded, and retrieved against the user’s question before generating the final answer. The important architectural point is that answering is **context-conditioned** rather than relying on a global knowledge store.

7. **Model and prompt layer**  
   `llm.py` and `prompts.py` separate the language-model call path from prompt construction. That means the backend likely has a clean split between:
   - prompt templates/instructions,
   - LLM invocation,
   - retrieval results assembled into the final answer.
   This helps keep the AI logic isolated from server and extraction logic.

8. **Utility/helper layer**  
   `helper.py` appears to hold shared backend utilities, such as text cleaning, chunking, formatting, or other support logic used by `server.py` and `llm.py`. In a diagram, this is a supporting internal module rather than a major subsystem.

9. **Data flow end to end**  
   The main request flow is:
   - user asks a question in the popup,
   - the extension identifies the active page/video,
   - context is sent to the Python backend,
   - the backend chunks and embeds the context,
   - relevant chunks are retrieved,
   - the LLM generates an answer,
   - the answer is returned to the popup for display.

10. **State and persistence boundary**  
   The system explicitly avoids persistent storage and history mixing. That means there is no central document database or user memory layer in the architecture. Each request is isolated to the current page/video context, which simplifies the diagram: no long-lived indexing service is required.

11. **Operational/runtime boundary**  
   The repo combines browser-side JavaScript and a Python service. The extension runs inside Chrome, while the AI pipeline runs in Python with dependencies listed in `requirements.txt`. That dependency split is the main deployment boundary to show.

12. **What matters most for the diagram**  
   The key boxes are:
   - **Chrome extension UI**,
   - **background/orchestration script**,
   - **context extraction from page/YouTube**,
   - **Python backend API**,
   - **RAG/LLM pipeline**,
   - **utility/prompt modules**.  
   The main arrows should show questions and page context flowing from the browser to the backend, and answers flowing back to the popup.

Main entry points: [`chrome-extension/background.js`](https://github.com/prithwin55/insightanywhere/blob/main/chrome-extension/background.js) (Background Bridge), [`server.py`](https://github.com/prithwin55/insightanywhere/blob/main/server.py) (API Server), [`chrome-extension/popup.js`](https://github.com/prithwin55/insightanywhere/blob/main/chrome-extension/popup.js) (Popup Logic), [`chrome-extension/popup.html`](https://github.com/prithwin55/insightanywhere/blob/main/chrome-extension/popup.html) (Popup UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_chrome_extension["Chrome Extension"]
  node_manifest["Manifest<br/>extension config<br/>[manifest.json]"]
  node_popup_ui["Popup UI<br/>browser UI<br/>[popup.html]"]
  node_popup_controller["Popup Logic<br/>UI controller<br/>[popup.js]"]
  node_background_bridge["Background Bridge<br/>extension coordinator<br/>[background.js]"]
  node_page_context["Page Context<br/>web extractor"]
  node_youtube_context["YouTube Context<br/>video extractor"]
  node_styles["Styles<br/>ui styling<br/>[styles.css]"]
end

subgraph group_python_backend["Python Backend"]
  node_server_api["API Server<br/>python entrypoint<br/>[server.py]"]
  node_request_pipeline["RAG Flow<br/>request pipeline"]
  node_prompt_layer["Prompts<br/>prompt templates<br/>[prompts.py]"]
  node_llm_layer["LLM Call<br/>model interface<br/>[llm.py]"]
  node_helper_utils["Helpers<br/>shared utilities<br/>[helper.py]"]
end

node_manifest -->|"declares"| node_popup_ui
node_popup_ui -->|"driven by"| node_popup_controller
node_popup_controller -->|"sends question"| node_background_bridge
node_background_bridge -->|"extracts"| node_page_context
node_background_bridge -->|"extracts"| node_youtube_context
node_background_bridge -->|"requests answer"| node_server_api
node_background_bridge -->|"uses"| node_styles
node_server_api -->|"orchestrates"| node_request_pipeline
node_request_pipeline -->|"uses"| node_helper_utils
node_request_pipeline -->|"builds prompt"| node_prompt_layer
node_request_pipeline -->|"generates answer"| node_llm_layer
node_llm_layer -->|"consumes"| node_prompt_layer
node_server_api -->|"validates"| node_helper_utils
node_popup_controller -->|"receives answer"| node_server_api

click node_manifest "https://github.com/prithwin55/insightanywhere/blob/main/chrome-extension/manifest.json"
click node_popup_ui "https://github.com/prithwin55/insightanywhere/blob/main/chrome-extension/popup.html"
click node_popup_controller "https://github.com/prithwin55/insightanywhere/blob/main/chrome-extension/popup.js"
click node_background_bridge "https://github.com/prithwin55/insightanywhere/blob/main/chrome-extension/background.js"
click node_styles "https://github.com/prithwin55/insightanywhere/blob/main/chrome-extension/styles.css"
click node_server_api "https://github.com/prithwin55/insightanywhere/blob/main/server.py"
click node_prompt_layer "https://github.com/prithwin55/insightanywhere/blob/main/prompts.py"
click node_llm_layer "https://github.com/prithwin55/insightanywhere/blob/main/llm.py"
click node_helper_utils "https://github.com/prithwin55/insightanywhere/blob/main/helper.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_manifest,node_popup_ui,node_popup_controller,node_background_bridge,node_page_context,node_youtube_context,node_styles toneBlue
class node_server_api,node_request_pipeline,node_prompt_layer,node_llm_layer,node_helper_utils toneAmber
```

## Components

### Chrome Extension

Browser-side UI and page-context capture runtime.

- [Manifest](https://github.com/prithwin55/insightanywhere/blob/main/chrome-extension/manifest.json): extension config · Extension entry points, permissions, and runtime wiring. · `chrome-extension/manifest.json`
- [Popup UI](https://github.com/prithwin55/insightanywhere/blob/main/chrome-extension/popup.html): browser UI · Lightweight chat surface shown in the browser. · `chrome-extension/popup.html`
- [Popup Logic](https://github.com/prithwin55/insightanywhere/blob/main/chrome-extension/popup.js): UI controller · Handles user input and renders answers in the popup. · `chrome-extension/popup.js`
- [Background Bridge](https://github.com/prithwin55/insightanywhere/blob/main/chrome-extension/background.js): extension coordinator · Bridges the popup, active tab context, and backend request. · `chrome-extension/background.js`
- **Page Context**: web extractor · Collects readable text from regular webpages.
- **YouTube Context**: video extractor · Collects title, description, and optional transcript data.
- [Styles](https://github.com/prithwin55/insightanywhere/blob/main/chrome-extension/styles.css): ui styling · Popup presentation and layout styling. · `chrome-extension/styles.css`

### Python Backend

Stateless request-time AI service and RAG pipeline.

- [API Server](https://github.com/prithwin55/insightanywhere/blob/main/server.py): python entrypoint · HTTP boundary between the extension and the AI pipeline. · `server.py`
- **RAG Flow**: request pipeline · Per-request chunking, embedding, retrieval, and answer assembly.
- [Prompts](https://github.com/prithwin55/insightanywhere/blob/main/prompts.py): prompt templates · Builds instructions and response framing for the model. · `prompts.py`
- [LLM Call](https://github.com/prithwin55/insightanywhere/blob/main/llm.py): model interface · Invokes the language model to generate the final answer. · `llm.py`
- [Helpers](https://github.com/prithwin55/insightanywhere/blob/main/helper.py): shared utilities · Common backend support for cleaning, chunking, and formatting. · `helper.py`

## Connections

- Manifest → Popup UI: declares · Registers the popup as the user-facing extension surface.
- Popup UI → Popup Logic: driven by · Popup markup is controlled by popup logic.
- Popup Logic → Background Bridge: sends question · User questions are handed off to the background script.
- Background Bridge → Page Context: extracts · Reads text from the active webpage.
- Background Bridge → YouTube Context: extracts · Reads video-specific context when on YouTube pages.
- Background Bridge → API Server: requests answer · Forwards question plus current-tab context to the backend.
- Background Bridge → Styles: uses · Popup presentation is styled separately from behavior.
- API Server → RAG Flow: orchestrates · Backend entrypoint coordinates the per-request RAG flow.
- RAG Flow → Helpers: uses · Shared helpers support cleaning, chunking, and formatting.
- RAG Flow → Prompts: builds prompt · Retrieval output is packaged with prompt instructions.
- RAG Flow → LLM Call: generates answer · The model produces the final context-conditioned response.
- LLM Call → Prompts: consumes · Model invocation depends on the constructed prompt.
- API Server → Helpers: validates · Helpers support request handling and input preparation.
- Popup Logic → API Server: receives answer · Returned answers flow back through the extension UI.
