SurfSense/_bmad-output/developer-guide.md

Hướng Dẫn Developer SurfSense

Dành cho Nhà Phát Triển

---

📖 Giới Thiệu

Tài liệu này hướng dẫn developers cách setup, develop, và extend hệ thống SurfSense.

---

🏗️ Kiến Trúc Tổng Quan

SurfSense bao gồm 3 components chính:

1. Backend (surfsense_backend) - Python/FastAPI
2. Web (surfsense_web) - Next.js 16
3. Extension (surfsense_browser_extension) - Plasmo/React

Xem chi tiết:

• Kiến Trúc Backend
• Kiến Trúc Web
• Kiến Trúc Extension
• Kiến Trúc Tích Hợp

---

🚀 Setup Development Environment

Prerequisites

• Python 3.11+
• Node.js 18+
• PostgreSQL 15+
• Redis
• Git

Clone Repository

git clone https://github.com/your-org/surfsense.git
cd surfsense

Backend Setup

cd surfsense_backend

# Create virtual environment
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Setup environment
cp .env.example .env
# Edit .env với database credentials, API keys

# Run migrations
alembic upgrade head

# Start server
uvicorn app.main:app --reload

Backend chạy tại: http://localhost:8000

Web Setup

cd surfsense_web

# Install dependencies
npm install

# Setup environment
cp .env.example .env.local
# Edit NEXT_PUBLIC_API_URL=http://localhost:8000

# Start dev server
npm run dev

Web chạy tại: http://localhost:3000

Extension Setup

cd surfsense_browser_extension

# Install dependencies
npm install

# Build extension
npm run dev

# Load extension trong Chrome:
# 1. Vào chrome://extensions/
# 2. Enable "Developer mode"
# 3. Click "Load unpacked"
# 4. Chọn folder build/chrome-mv3-dev

---

🗂️ Cấu Trúc Dự Án

Backend Structure

surfsense_backend/
├── app/
│   ├── api/          # API routes
│   ├── core/         # Core logic (auth, config)
│   ├── db/           # Database models
│   ├── services/     # Business logic
│   └── main.py       # FastAPI app
├── alembic/          # Database migrations
├── tests/            # Unit tests
└── requirements.txt

Web Structure

surfsense_web/
├── app/              # Next.js App Router
│   ├── (auth)/       # Auth pages
│   ├── (dashboard)/  # Dashboard pages
│   └── api/          # API routes
├── components/       # React components
├── lib/              # Utilities
└── public/           # Static assets

Extension Structure

surfsense_browser_extension/
├── src/
│   ├── background/   # Background service
│   ├── popup/        # Popup UI
│   ├── content/      # Content scripts
│   └── components/   # Shared components
└── manifest.json     # Extension manifest

---

🔌 API Reference

Authentication

Login:

POST /api/auth/login
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "password123"
}

# Response:
{
  "access_token": "eyJ...",
  "token_type": "bearer"
}

Sử dụng token:

GET /api/content
Authorization: Bearer eyJ...

Content Management

Capture content:

POST /api/content
Authorization: Bearer <token>
Content-Type: application/json

{
  "url": "https://example.com",
  "title": "Example Page",
  "body": "Content text...",
  "tags": ["research", "ai"]
}

Search:

GET /api/search?q=machine+learning&limit=10
Authorization: Bearer <token>

AI Chat

Send message:

POST /api/ai/chat
Authorization: Bearer <token>
Content-Type: application/json

{
  "message": "Summarize my AI research",
  "mode": "research"  # "chat" | "research"
}

Xem chi tiết: API Contracts

---

🗄️ Database Schema

Core Tables

users:

• id (UUID, PK)
• email (unique)
• hashed_password
• role (user | admin | superadmin)
• plan (free | pro | enterprise)

content:

• id (UUID, PK)
• user_id (FK → users)
• url, title, body
• tags (JSONB)
• created_at

collections:

• id (UUID, PK)
• user_id (FK → users)
• name, description

Xem chi tiết: Data Models

---

🧪 Testing

Backend Tests

cd surfsense_backend

# Run all tests
pytest

# Run specific test
pytest tests/test_auth.py

# With coverage
pytest --cov=app tests/

Web Tests

cd surfsense_web

# Run unit tests
npm test

# Run E2E tests
npm run test:e2e

Extension Tests

cd surfsense_browser_extension

# Run tests
npm test

---

🔧 Common Development Tasks

Tạo API Endpoint Mới

1. Tạo route (app/api/routes/example.py):

from fastapi import APIRouter, Depends
from app.core.auth import get_current_user

router = APIRouter()

@router.get("/example")
async def get_example(user = Depends(get_current_user)):
    return {"message": "Hello", "user_id": user.id}

2. Register route (app/api/__init__.py):

from app.api.routes import example

api_router.include_router(example.router, prefix="/example", tags=["example"])

Tạo Database Migration

cd surfsense_backend

# Auto-generate migration
alembic revision --autogenerate -m "Add new_column to users"

# Review migration file in alembic/versions/

# Apply migration
alembic upgrade head

Thêm React Component Mới

1. Tạo component (components/MyComponent.tsx):

export function MyComponent({ title }: { title: string }) {
  return <div>{title}</div>
}

2. Sử dụng:

import { MyComponent } from '@/components/MyComponent'

export default function Page() {
  return <MyComponent title="Hello" />
}

---

🚢 Deployment

Build Production

Backend:

cd surfsense_backend
pip install -r requirements.txt
uvicorn app.main:app --host 0.0.0.0 --port 8000 --workers 4

Web:

cd surfsense_web
npm run build
npm start

Extension:

cd surfsense_browser_extension
npm run build
# Upload build/chrome-mv3-prod to Chrome Web Store

Docker Deployment

docker-compose up -d

Xem chi tiết deployment trong Admin Guide.

---

🐛 Debugging

Backend Debugging

Enable debug logs:

# .env
LOG_LEVEL=DEBUG

Use debugger:

import pdb; pdb.set_trace()

Web Debugging

Next.js debug mode:

NODE_OPTIONS='--inspect' npm run dev

React DevTools: Install extension

Extension Debugging

1. Vào chrome://extensions/
2. Click "Inspect views: background page"
3. Sử dụng Chrome DevTools

---

📚 Tài Nguyên Bổ Sung

Documentation

• FastAPI Docs
• Next.js Docs
• Plasmo Docs

Code Style

• Backend: PEP 8, Black formatter
• Web/Extension: ESLint, Prettier

Git Workflow

• Branch naming: feature/, bugfix/, hotfix/
• Commit messages: Conventional Commits
• PR template: Mô tả changes, testing done

---

Cập nhật: 2026-01-31 | Version: 1.0