Core Annotation Engine

Relevant source files

The following files were used as context for generating this wiki page:

• extension/src/content/index.ts
• extension/src/background/index.ts
• packages/shared/src/types.ts
• extension/src/content/manual.ts
• backend/config/prompts.json
• README.md

The Core Annotation Engine is the central processing unit for the Oddity 1 platform. It orchestrates text extraction, AI-driven analysis, and the multi-layered rendering of annotations across web pages and documents. The engine supports various modes, including structured overviews, deep critical analysis, and manual user-created notes.

It coordinates interactions between the Chrome extension's content scripts, the background service worker, and the backend LLM endpoints. The engine is specifically optimized for complex prose such as research papers, articles, and streaming LLM chat transcripts.

Sources: README.md:120-140, extension/src/content/index.ts:24-100, backend/config/prompts.json:2-10

Architecture and Data Flow

The engine operates across three distinct environments: the host web page (Content Script), the extension process (Background Script), and the remote server (Backend).

1. Detection & Extraction: The Content Script identifies reading regions using site-specific adapters, Mozilla Readability, or custom heuristics.
2. Request Orchestration: The Background Script manages authentication, rate limiting, and session caching.
3. Annotation Generation: The Backend utilizes structured LLM prompts to generate annotations based on the selected mode and personality.
4. Rendering: The Content Script injects anchor spans and renders high-performance overlays and margin notes.

Data Flow Diagram

The following diagram illustrates the sequence from text detection to final rendering on the page.

Annotation Modes and Personalities

The engine supports two primary AI-driven modes, which dictate the logic used by the backend generation process.

Overview Mode

Overview mode generates a structural skeleton of the text. It divides content into contiguous chunks (target 250–350 words) and provides a sequential summary that captures the logical progression of the argument.
Sources: backend/config/prompts.json:4-22, packages/shared/src/types.ts:4-10

Depth Mode

Depth mode provides marginalia-style analysis through specific "personalities." These personalities are guided by unique system prompts:

Personality	Role	Cognitive Signature
Terry	Provocateur	Focuses on logical flaws, evidential gaps, and load-bearing assumptions.
Jerry	Catalyst	Exercises creativity and metacognition via juxtaposition and frame-breaking.
Sally	Surgical Provocateur	Direct, short-form provocations naming specific limitations or biases.

Sources: backend/config/prompts.json:66-77, backend/config/prompts.json:151-165, packages/shared/src/types.ts:16-41

Manual Annotation System

Users can create custom annotations by selecting text on a page. This system bypasses the LLM generation pipeline and utilizes a local UI for input.

• Trigger: The manual.ts module listens for selectionchange and mouseup events.
• Floating Action Button (FAB): A pencil icon appears near the selection to open the editor.
• Storage: Manual annotations are saved to the backend via saveManualAnnotation and persisted in chrome.storage.local.
• Interaction: Supports editing via inline textareas and immediate deletion with DOM cleanup.

Google Docs Integration

The engine includes specialized logic for Google Docs, which uses a canvas-based rendering engine rather than standard HTML elements.

• Extraction: Text is extracted via a dedicated helper extractGoogleDocsText that handles the internal KIX editor structure.
• Positioning: Because standard DOM ranges do not work, the engine uses findAnnotationRects to calculate absolute pixel positions for highlights.
• Overlay: High-performance overlay rects are set to pointer-events: none to allow standard editing while maintaining visual annotations.
• Edit Tracking: The engine monitors line shifts and character inputs to adjust annotation positions in real-time as the user types.

Sources: extension/src/content/index.ts:672-747, extension/src/background/index.ts:160-220

Caching and Optimization

To minimize latency, the engine implements a multi-tier caching strategy:

1. Session Cache: In-memory storage in the Service Worker for instant revisits within a session.
2. URL Prediction Cache: Stores successful annotation hashes per URL in chrome.storage.local to trigger speculative rendering on page load.
3. Backend Cache: The annotation_cache table in Supabase stores AI results keyed by content_hash and intensity for 30 days.

Sources: extension/src/background/sw-cache.ts, extension/src/background/url-cache.ts, README.md:213-217, extension/src/background/index.ts:246-265

Technical Specifications

Data Structures

export type Annotation = {
  id: string;
  mode: AnnotationMode;
  type: AnnotationType;
  label?: string;
  anchor: TextQuoteSelector;
  content: {
    note: string;
    why_it_matters?: string;
    question?: string;
  };
};

Sources: packages/shared/src/types.ts:65-80

API Endpoints

Method	Path	Description
POST	/api/annotate	Generates AI annotations (cached, streaming support).
GET	/api/annotations	Fetches cached and user-created annotations for a specific URL.
DELETE	/api/annotations/:id	Removes an annotation and its associated anchors.

Sources: README.md:200-210, extension/src/background/api-client.ts

The Core Annotation Engine facilitates a sophisticated interaction between static content and dynamic AI analysis, ensuring that annotations remain accurate and performant across diverse web environments, including traditional articles, complex Google Docs, and streaming chatbot interfaces.