# aryankeluskar/alice architecture

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

- Interactive diagram: https://gitdiagram.com/aryankeluskar/alice
- Repository: https://github.com/aryankeluskar/alice

## Overview

##### Project Type and Purpose
- Alice is an open-source browser extension (Chrome/Firefox) built on top of Mozilla’s pdf.js library.
- Its purpose is to enrich research-paper reading by letting users hover over citations in a PDF and see instant metadata (title, authors, year), AI-generated summaries, and code links (e.g., PapersWithCode) without leaving the PDF.

##### File Structure & Architectural Insights
- Top-level “extensions/chromium”: contains manifest.json, content scripts, background scripts, UI pages, and CSS for the extension.
- “web/”: houses modified pdf.js viewer UI code (HTML, JS, CSS) that the extension injects or uses.
- “src/” and “external/”: upstream pdf.js core engine, decoders, worker scripts, localization, and wasm modules.
- No backend servers or databases— all API calls (arXiv, Gemini, Claude, PapersWithCode) are direct from the extension’s background script or content script.
- Build scripts (gulpfile.mjs), config files, localization directories indicate a modular, plugin-like architecture.

##### Main Components
a. Browser Host
- PDF Viewer frame (leveraging pdf.js UI)
- Extension Content Script (injected into PDF pages)
b. Extension Background Script
- Listens for hover events forwarded by content script
- Manages long-lived tasks (rate-limiting, caching)
c. Popup UI / Overlay
- Small HTML/CSS panel injected by content script to show metadata, summary, code links
d. External Services
- arXiv API (metadata lookup)
- AI Providers: Google Gemini (summarization), Claude Sonnet (code-generation prompts)
- PapersWithCode (code-link generation)
e. pdf.js Engine
- Core parsing and rendering (WebWorker + main thread)
- Exposed APIs for locating citation text spans

##### Component Interactions & Data Flow
1. User hovers over citation text in the PDF.
2. Content Script detects the DOM element & extracts citation identifier (e.g., DOI, arXiv ID).
3. Content Script → sends message to Background Script via WebExtension Messaging API.
4. Background Script → fetches metadata from arXiv API.
5. Background Script → sends metadata to AI Provider (Gemini) for summary (if summarization feature enabled).
6. Background Script → prompts Claude Sonnet to generate PapersWithCode-style code instructions.
7. Background Script → sends aggregated result back to Content Script.
8. Content Script → renders Popup UI overlay adjacent to citation with:
- Title, authors, year
- AI-generated summary
- Code-generation link (PapersWithCode embed)

##### Architectural Patterns and Principles
- Event-driven architecture: hover events trigger an async pipeline.
- Separation of concerns: content script handles DOM, background script handles network/API calls and rate-limiting.
- Plugin-style pdf.js integration: uses pdf.js APIs without modifying engine internals.
- No central data store—stateless calls with ephemeral caching in-memory or browser.storage.local.

##### Emphasizing AI-Assistance & Citation Preview
- “arXiv Metadata API” → returns JSON with title/authors/year
- “AI Summarizer (Gemini)” → returns a concise summary
- “Code Generator (Claude Sonnet + PapersWithCode)” → returns an embeddable code link
- Data flow to show where the extension orchestrates multiple parallel API calls and then aggregates results.

## Diagram (Mermaid)

```mermaid
graph TB
    %% In-Browser Components
    subgraph "Browser + pdf.js Viewer" 
        direction TB
        ViewerUI["PDF Viewer UI (web/viewer.html, web/viewer.js)"]:::frontend
        PDFEngine["pdf.js Core Engine"]:::frontend
        ViewerUI -->|"renders using"| PDFEngine
    end

    %% Extension Scripts
    subgraph "Extension Scripts" 
        direction TB
        ContentScript["Content Script"]:::extension
        PDFHandler["PDF Handler Integration"]:::extension
        MessageRouter["Extension Message Router"]:::extension
        BackgroundScript["Background Script"]:::extension
        ClaudeHandler["Code Generator Handler"]:::extension
        ContentScript -->|"intercepts hover"| PDFHandler
        PDFHandler -->|"identifies citation"| ContentScript
        ContentScript -->|"send message"| MessageRouter
        MessageRouter -->|"routes to"| BackgroundScript
        BackgroundScript -->|"calls"| ClaudeHandler
    end

    %% Popup UI
    PopupUI["Citation Popup UI Overlay"]:::frontend

    BackgroundScript -->|"send aggregated data"| ContentScript
    ContentScript -->|"render overlay"| PopupUI

    %% External Services
    subgraph "External AI & Metadata Services"
        direction TB
        Arxiv["arXiv Metadata API"]:::external
        AIModel["AI Summarizer (Gemini)"]:::external
        CodeAPI["Code Generator (Claude Sonnet + PapersWithCode)"]:::external
    end

    BackgroundScript -->|"fetch metadata"| Arxiv
    BackgroundScript -->|"request summary"| AIModel
    BackgroundScript -->|"request code link"| CodeAPI

    %% Styles
    classDef frontend fill:#add8e6,stroke:#000,stroke-width:1px;
    classDef extension fill:#90ee90,stroke:#000,stroke-width:1px;
    classDef external fill:#ffa500,stroke:#000,stroke-width:1px;

    %% Click Events
    click ViewerUI "https://github.com/aryankeluskar/alice/blob/master/web/viewer.html"
    click ViewerUI "https://github.com/aryankeluskar/alice/blob/master/web/viewer.js"
    click PDFEngine "https://github.com/aryankeluskar/alice/blob/master/src/pdf.js"
    click PDFEngine "https://github.com/aryankeluskar/alice/blob/master/src/pdf.worker.js"
    click PDFEngine "https://github.com/aryankeluskar/alice/blob/master/src/core/worker.js"
    click ContentScript "https://github.com/aryankeluskar/alice/blob/master/extensions/chromium/contentscript.js"
    click PDFHandler "https://github.com/aryankeluskar/alice/blob/master/extensions/chromium/pdfHandler.js"
    click MessageRouter "https://github.com/aryankeluskar/alice/blob/master/extensions/chromium/extension-router.js"
    click BackgroundScript "https://github.com/aryankeluskar/alice/blob/master/extensions/chromium/background.js"
    click ClaudeHandler "https://github.com/aryankeluskar/alice/blob/master/extensions/chromium/claude-api-handler.js"
    click PopupUI "https://github.com/aryankeluskar/alice/blob/master/web/viewer-snippet-chrome-extension.html"
    click PopupUI "https://github.com/aryankeluskar/alice/blob/master/extensions/chromium/contentstyle.css"
```
