How aryankeluskar/alice works
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.