Pufferfish Extension Development Assistant

Expert assistant for the Pufferfish video fact-checking platform. Specializes in Chrome extension development, YouTube integration, compliance enforcement, and microservices architecture.

Project Overview

Pufferfish is a browser extension for real-time video fact-checking with platform-specific compliance, transcript/frame analysis, and AI-powered verification.

**Architecture:** Turbo monorepo with WXT-based Chrome extension, FastAPI gateway, Elasticsearch vector search, LangGraph orchestration, and specialized microservices (STT, OCR, LLM).

**Repository:** `/Users/seanm-github/Documents/ClaudeCodeProjects/Pufferfish`

Instructions

When working on Pufferfish:

1. Extension Development (apps/extension)

**Framework:** WXT (Web Extension Toolkit) for modern WebExtension development

**Fallback:** Vanilla JavaScript MVP exists (`manifest.json`, `background.js`, `content.js`, `youtube-overlay.js`)

**Migration Path:** Convert vanilla JS to TypeScript + React when npm dependencies resolve

**Activation Methods:**

- Extension toolbar button click

- Context menu ("Fact-check video on this page")

- Keyboard shortcut (Cmd+Shift+F / Ctrl+Shift+F)

- YouTube player button (custom overlay)

**Key Files:**

`apps/extension/manifest.json` - Chrome manifest v3

`apps/extension/background.js` - Service worker (vanilla JS)

`apps/extension/content.js` - Content script for video detection

`apps/extension/youtube-overlay.js` - YouTube player integration

`apps/extension/wxt.config.ts` - WXT configuration (when migrating)

**Video Detection:**

Use MutationObserver to detect dynamically loaded videos (YouTube SPA behavior).

**Loading Extension:**

```bash

Chrome: chrome://extensions/ → Developer mode → Load unpacked

Select: /Users/seanm-github/Documents/ClaudeCodeProjects/Pufferfish/apps/extension

```

2. Platform Compliance (Critical)

Enforce platform-specific policies at the content script level:

|----------|------------|-------------------|--------|

**Implementation:**

`apps/extension/src/content/policy.ts` - Policy engine

Reject disallowed actions in content script before sending to backend

3. Microservices Backend

**Services:**

**Gateway** (`services/gateway/`) - FastAPI WebSocket API, request routing

**STT** (`services/stt/`) - OpenAI Whisper for speech-to-text (GPU-accelerated)

**OCR** (`services/ocr/`) - PaddleOCR for frame text extraction

**LLM** (`services/llm/`) - Ollama/Gemma2 for claim extraction

**Orchestrator** (`services/orchestrator/`) - LangGraph workflow coordination

**Local Development:**

```bash

Start all services

make docker-up

Setup Elasticsearch indices

make setup-elastic

View logs

docker-compose logs -f gateway

```

4. Elasticsearch Configuration

**Index:** `facts`

**Schema:**

`claim_text` (text) - Full-text search

`claim_embedding` (dense_vector, 768d) - Semantic search

`source_domain`, `timestamp`, `confidence_score` - Filters

**Search Strategy:** Hybrid (RRF) combining BM25 and kNN dense vectors.

5. Monorepo Commands

```bash

Install dependencies

npm install --legacy-peer-deps

Build all packages

turbo build

Develop extension

cd apps/extension

turbo dev

Lint/format

turbo lint

turbo format

Run tests

turbo test

```

6. Common Issues & Solutions

**npm Dependency Resolution (macOS):**

Error: `WXT/mlly/pathe` version conflicts

Solution: Use `--legacy-peer-deps` or vanilla JS fallback

When fixed: Migrate to TypeScript via WXT entrypoints

**YouTube Context Menu:**

Cannot modify video player's native menu (security restriction)

Use: Page-level context menu + custom player button + keyboard shortcuts

**Video Detection:**

YouTube loads videos dynamically (SPA)

Use: MutationObserver watching for `<video>` elements

7. File Structure (Key Paths)

```

apps/

extension/ # Chrome extension (WXT framework)

manifest.json # Manifest v3 (vanilla JS)

background.js # Service worker

content.js # Video detector

youtube-overlay.js # YouTube player button

src/

entrypoints/ # WXT TypeScript (future)

content/ # Content scripts

policy.ts # Platform compliance engine

components/ # React UI (future)

services/

gateway/ # FastAPI WebSocket server

stt/ # Whisper speech-to-text

ocr/ # PaddleOCR text extraction

llm/ # Ollama/Gemma2 claim extraction

orchestrator/ # LangGraph workflow

packages/

shared/ # Shared TypeScript types

ui/ # Shared React components

docker-compose.yml # Local services stack

Makefile # Development commands

turbo.json # Build pipeline config

```

8. Development Workflow

**For Extension Changes:**

1. Edit files in `apps/extension/`

2. Reload extension in `chrome://extensions/`

3. Test on YouTube or CNN

4. Check console for errors

5. Verify compliance (no overlays on YouTube, 0.5 FPS on CNN)

**For Backend Changes:**

1. Edit service in `services/*/`

2. Restart container: `docker-compose restart <service>`

3. Check logs: `docker-compose logs -f <service>`

4. Test WebSocket connection from extension

**For Shared Code:**

1. Edit in `packages/shared/` or `packages/ui/`

2. Run `turbo build` to rebuild dependents

3. Reload extension if affected

9. Testing Strategy

**Manual Testing:**

YouTube video detection + transcript extraction

CNN frame extraction (verify 0.5 FPS limit)

Context menu appearance on all platforms

Extension toolbar button click

Keyboard shortcut (Cmd+Shift+F / Ctrl+Shift+F)

Visual notification animations

**Automated Testing (Future):**

`turbo test` - Run all package tests

Playwright for extension E2E tests

Jest for unit tests

10. Next Development Priorities

**Sprint 1 (Current):**

1. Resolve npm dependencies for WXT TypeScript migration

2. Implement policy engine (`apps/extension/src/content/policy.ts`)

3. Add extension icons (icon-16.png, icon-48.png, icon-128.png)

4. Load `youtube-overlay.js` in manifest

5. Connect extension to backend WebSocket

**Sprint 2:**

1. Deploy Elasticsearch cluster

2. Implement FastAPI gateway with WebSocket

3. Create STT service with Whisper

4. Build OCR service with PaddleOCR

5. Implement LangGraph orchestration workflow

**Sprint 3:**

1. Build React UI for fact-check results

2. Add confidence scoring visualization

3. Implement source attribution overlay

4. Add user settings (enable/disable platforms, sensitivity)

5. Create onboarding flow

11. Constraints & Guidelines

**Compliance First:** Never implement features violating platform TOS

**Performance:** Extension must not slow down page load (<100ms overhead)

**Privacy:** No PII collection, all video analysis server-side

**Fair Use:** Max 30-second clips, automatic attribution, educational purpose

**Accessibility:** WCAG 2.1 AA compliance for all UI elements

**TypeScript:** Strict mode enabled, no `any` types

**Code Style:** Prettier + ESLint auto-formatting enforced

12. Resources

**Documentation:**

`README.md` - Architecture overview, setup guide

`CLAUDE.md` (this file) - Session memory, technical notes

**External:**

[WXT Documentation](https://wxt.dev/)

[Chrome Extension API](https://developer.chrome.com/docs/extensions/)

[YouTube IFrame API](https://developers.google.com/youtube/iframe_api_reference)

[Elasticsearch Vector Search](https://www.elastic.co/guide/en/elasticsearch/reference/current/knn-search.html)

13. Commands Reference

```bash

Development

make docker-up # Start all services

make docker-down # Stop all services

make setup-elastic # Initialize Elasticsearch indices

make logs SERVICE=gateway # View service logs

Extension

Load unpacked from: apps/extension/

Monorepo

npm install --legacy-peer-deps # Install dependencies

turbo build # Build all packages

turbo dev # Watch mode for all packages

turbo lint # Lint all packages

turbo format # Format all packages

turbo test # Run all tests

Cleanup

rm -rf node_modules apps/*/node_modules packages/*/node_modules

npm cache clean --force

```

Examples

Example 1: Adding a New Platform

When adding support for a new video platform (e.g., TikTok):

1. **Update policy engine** (`apps/extension/src/content/policy.ts`):

```typescript

export const PLATFORM_POLICIES = {

'tiktok.com': {

allowedUI: ['adjacent-panel'],

contentExtraction: {

frames: true,

fps: 0.5,

transcripts: true

fairUse: {

maxClipLength: 15, // TikTok videos are short

requireAttribution: true

}

```

2. **Create platform detector** (`apps/extension/src/content/detectors/tiktok.ts`):

```typescript

export class TikTokDetector implements VideoDetector {

detect(): VideoElement | null {

return document.querySelector('video[src*="tiktok"]')

}

```

3. **Register in content script** (`apps/extension/content.js`):

```javascript

const detectors = [

new YouTubeDetector(),

new CNNDetector(),

new TikTokDetector()

]

```

4. **Test compliance:**

Verify 0.5 FPS frame extraction limit

Confirm 15-second clip max

Check attribution overlay displays

Example 2: Implementing WebSocket Connection

Connect extension to backend gateway:

1. **In background service worker** (`apps/extension/background.js`):

```javascript

let ws = null

function connectWebSocket() {

ws = new WebSocket('ws://localhost:8000/ws')

ws.onopen = () => console.log('Connected to gateway')

ws.onmessage = (event) => {

const data = JSON.parse(event.data)

// Handle fact-check results

chrome.tabs.sendMessage(data.tabId, {

type: 'FACTCHECK_RESULT',

payload: data

})

}

ws.onerror = (error) => console.error('WebSocket error:', error)

ws.onclose = () => setTimeout(connectWebSocket, 5000) // Reconnect

}

connectWebSocket()

```

2. **Send video data** (from content script):

```javascript

chrome.runtime.sendMessage({

type: 'FACTCHECK_REQUEST',

video: {

url: window.location.href,

platform: 'youtube.com',

transcript: extractedTranscript

}

})

```

3. **In background worker** (forward to WebSocket):

```javascript

chrome.runtime.onMessage.addListener((message, sender) => {

if (message.type === 'FACTCHECK_REQUEST') {

ws.send(JSON.stringify({

tabId: sender.tab.id,

video: message.video

}))

}

})

```

Example 3: Implementing YouTube Transcript Extraction

Extract YouTube captions without violating TOS:

1. **Use official API** (in content script):

```javascript

async function getYouTubeTranscript(videoId) {

const response = await fetch(

`https://www.youtube.com/api/timedtext?v=${videoId}&lang=en`

)

const xml = await response.text()

const parser = new DOMParser()

const doc = parser.parseFromString(xml, 'text/xml')

return Array.from(doc.querySelectorAll('text')).map(node => ({

start: parseFloat(node.getAttribute('start')),

duration: parseFloat(node.getAttribute('dur')),

text: node.textContent

}))

}

```

2. **Check policy before extraction**:

```javascript

import { canExtractTranscript } from './policy'

if (canExtractTranscript('youtube.com')) {

const transcript = await getYouTubeTranscript(videoId)

sendToBackend(transcript)

} else {

console.warn('Transcript extraction not allowed on this platform')

}

```

Notes

**Current State:** Working Chrome extension MVP in vanilla JavaScript. Backend services not yet deployed.

**Blockers:** npm dependency resolution for WXT TypeScript migration on macOS.

**Recent Session:** 2025-08-24 - Implemented MVP extension with multiple activation methods, YouTube player button, visual notifications.

**Repository Not Committed Yet:** Ready for initial commit when dependencies resolve.

Pufferfish Extension Development Assistant

Safety Concern

Pufferfish Extension Development Assistant

Project Overview

Instructions

1. Extension Development (apps/extension)

Chrome: chrome://extensions/ → Developer mode → Load unpacked

Select: /Users/seanm-github/Documents/ClaudeCodeProjects/Pufferfish/apps/extension

2. Platform Compliance (Critical)

3. Microservices Backend

Start all services

Setup Elasticsearch indices

View logs

4. Elasticsearch Configuration

5. Monorepo Commands

Install dependencies

Build all packages

Develop extension

Lint/format

Run tests

6. Common Issues & Solutions

7. File Structure (Key Paths)

8. Development Workflow

9. Testing Strategy

10. Next Development Priorities

11. Constraints & Guidelines

12. Resources

13. Commands Reference

Development

Extension

Load unpacked from: apps/extension/

Monorepo

Cleanup

Examples

Example 1: Adding a New Platform

Example 2: Implementing WebSocket Connection

Example 3: Implementing YouTube Transcript Extraction

Notes

Reviews (0)