SurfSense/_bmad-epics/epic-1-extension-core-infrastructure.md

Epic 1: Extension Core Infrastructure

Status: ✅ COMPLETED
Phase: Phase 1
Duration: 2 weeks
Priority: P0 (Critical)

---

Epic Overview

Xây dựng nền tảng cơ bản cho Chrome Extension với Side Panel architecture, tích hợp AI chat interface từ frontend, và context detection cho các trang crypto.

Business Value:

• Cho phép users chat với AI ngay trong browser
• Tự động detect và extract thông tin token từ DexScreener
• Tái sử dụng tối đa frontend components (giảm development time)
• Foundation cho tất cả features sau này

---

User Stories

Story 1.1: Side Panel Architecture

[FR-EXT-01]

Là một crypto trader,
Tôi muốn mở AI assistant dưới dạng side panel (không phải popup nhỏ),
Để tôi có thể chat với AI trong khi vẫn xem được DexScreener chart.

Acceptance Criteria:

• Extension icon click → Mở side panel bên phải màn hình
• Side panel width: 400px (default), resizable 300-600px
• Side panel không che khuất nội dung chính
• Side panel persist khi switch tabs
• Manifest có permission sidePanel

Technical Notes:

// background/index.ts
chrome.sidePanel
  .setPanelBehavior({ openPanelOnActionClick: true })
  .catch((error) => console.error("Failed to set side panel behavior:", error));

Files:

• surfsense_browser_extension/sidepanel.tsx ✅
• surfsense_browser_extension/package.json (add sidePanel permission) ✅

---

Story 1.2: AI Chat Interface Integration

[FR-EXT-02]

Là một crypto trader,
Tôi muốn chat với AI trong extension giống như trên web dashboard,
Để tôi có trải nghiệm nhất quán và đầy đủ tính năng.

Acceptance Criteria:

• Tích hợp @assistant-ui/react Thread component
• Streaming responses hoạt động
• Thinking steps visualization hiển thị
• Tool UIs render đúng (images, links, scraping)
• Attachment handling (upload files/images)
• Chat history lưu vào Plasmo Storage
• Chat history sync với backend API

Component Reuse:

// From frontend
import { Thread } from "@/components/assistant-ui/thread";
import { DisplayImageToolUI } from "@/components/tool-ui/display-image";
import { LinkPreviewToolUI } from "@/components/tool-ui/link-preview";
import { ScrapeWebpageToolUI } from "@/components/tool-ui/scrape-webpage";

Files:

• sidepanel/chat/ChatInterface.tsx ✅
• sidepanel/chat/ChatMessages.tsx ✅
• sidepanel/chat/ChatInput.tsx ✅
• sidepanel/chat/ChatHeader.tsx ✅

---

Story 1.3: Page Context Detection

[FR-EXT-03]

Là một crypto trader đang xem DexScreener,
Tôi muốn AI tự động hiểu tôi đang xem token nào,
Để tôi không cần copy/paste token address mỗi lần.

Acceptance Criteria:

• Content script detect page type:
  • DexScreener → Extract token data
  • CoinGecko → Extract coin info
  • Twitter/X → Extract crypto discussions
  • Generic → Basic page info
• Token data extracted:
  • Token address
  • Chain (Solana, Ethereum, Base)
  • Price, volume, liquidity
  • Pair info
• Context injected vào chat: "You are viewing $TOKEN on Solana..."
• Context updates khi user navigate to different token

Technical Implementation:

// content.ts
function detectPageType(): PageType {
  const hostname = window.location.hostname;
  if (hostname.includes('dexscreener.com')) return 'dexscreener';
  if (hostname.includes('coingecko.com')) return 'coingecko';
  if (hostname.includes('twitter.com') || hostname.includes('x.com')) return 'twitter';
  return 'generic';
}

function extractDexScreenerData(): TokenData {
  // Extract from URL: /solana/address
  // Or from page DOM
}

Files:

• content.ts ✅
• sidepanel/context/PageContextProvider.tsx ✅

---

Story 1.4: DexScreener Smart Integration

[FR-EXT-04]

Là một crypto trader trên DexScreener,
Tôi muốn thấy token info card ở top của side panel,
Để tôi có thể nhanh chóng check safety hoặc xem holders.

Acceptance Criteria:

• Token Info Card hiển thị khi detect DexScreener page
• Card shows:
  • Token symbol/name
  • Current price
  • 24h change (%)
  • Volume 24h
  • Liquidity
• Quick action buttons:
  • "Is this token safe?" → Trigger safety check
  • "Show top holders" → Query blockchain
  • "Price prediction" → AI analysis
• Buttons trigger chat with pre-filled context
• Auto-context: "this token" = token đang xem

UI Design:

┌─────────────────────────────┐
│ 🪙 BULLA/SOL               │
│ $0.0001  📈 +15%           │
│ Vol: $10K | Liq: $5K       │
│ [Safety Check] [Holders]   │
└─────────────────────────────┘

Files:

• sidepanel/dexscreener/TokenInfoCard.tsx ✅
• sidepanel/chat/ChatInterface.tsx (integrate card) ✅

---

Story 1.5: Quick Capture

[FR-EXT-05]

Là một crypto trader,
Tôi muốn save current page vào search space,
Để tôi có thể reference lại sau.

Acceptance Criteria:

• "📸 Save Current Page" button ở bottom của side panel
• Button sticky (luôn visible)
• Click → Capture page content
• Save vào selected search space
• Toast notification: "Page saved successfully"
• Reuse existing capture functionality

Files:

• sidepanel/chat/QuickCapture.tsx ✅

---

Story 1.6: Settings Sync với Frontend

[FR-EXT-06]

Là một SurfSense user,
Tôi muốn extension sử dụng cùng model và search space như web dashboard,
Để tôi không phải config lại.

Acceptance Criteria:

• Settings dropdown trong extension header
• Dropdown shows:
  • Current model (read-only)
  • Current search space (read-only)
  • Links to frontend management
• Links:
  • "Manage Connectors" → Open frontend /settings/connectors
  • "View All Chats" → Open frontend /chats
  • "Full Settings" → Open frontend /settings
• State sync:
  • Extension reads from backend API
  • Model selection synced
  • Search space synced
  • Enabled connectors synced (read-only)
  • Chat history bidirectional sync

API Endpoints Needed:

GET  /api/user/settings
POST /api/user/settings
GET  /api/models/available
GET  /api/search-spaces
GET  /api/connectors/enabled

Plasmo Storage Structure:

interface ExtensionStorage {
  settings: {
    selectedModel: string;
    searchSpaceId: string;
    apiKey: string;
  };
  cachedSettings: UserSettings;
  lastSync: number;
}

Files:

• sidepanel/chat/ChatHeader.tsx (add settings dropdown)
• lib/api/settings-sync.ts (new)

---

Technical Dependencies

Frontend Components to Reuse

• @assistant-ui/react Thread
• Tool UIs (images, links, scraping)
• Thinking steps visualization
• Chat utilities

Backend APIs Needed

• /api/user/settings - Get/update user settings
• /api/models/available - List available models
• /api/search-spaces - List search spaces
• /api/connectors/enabled - List enabled connectors
• /api/chat/stream - Chat streaming (existing)

Chrome APIs Used

• chrome.sidePanel - Side panel management
• chrome.storage - Plasmo Storage
• chrome.tabs - Tab management
• chrome.runtime - Messaging

---

Testing Strategy

Unit Tests

• PageContextProvider state management
• Token data extraction from DexScreener
• Settings sync logic

Integration Tests

• Side panel opens on icon click
• Chat streaming works
• Context detection works on DexScreener
• Token card displays correctly
• Quick capture saves page

Manual Testing

• Test on DexScreener.com
• Test on CoinGecko
• Test on Twitter
• Test settings sync with frontend
• Test chat history persistence

---

Definition of Done

• All 6 stories completed
• All acceptance criteria met
• Unit tests passing
• Integration tests passing
• Manual testing completed
• Code reviewed
• Documentation updated
• Deployed to staging

---

Notes

Phase 1 Status: ✅ COMPLETED (as of 2026-02-01)

Next Epic: Epic 2 - Smart Monitoring & Alerts (Phase 2)