SurfSense/_bmad-output/project-context.md

project_name	user_name	date	sections_completed	existing_patterns_found
SurfSense	Luisphan	2026-04-12	technology_stack	10

Project Context for AI Agents

This file contains critical rules and patterns that AI agents must follow when implementing code in this project. Focus on unobvious details that agents might otherwise miss.

---

Technology Stack & Versions

• Backend: Python >= 3.12, FastAPI (0.115.8), PostgreSQL (asyncpg, pgvector 0.3.6).
• Frontend (Web/Extension): Next.js (16.1.0) App Router (có Turbopack), React (19.2.3), TypeScript (5.8.3), TailwindCSS (4.1.11).
• ORM & Database State: Drizzle ORM (0.44.5) cho Frontend, SQLAlchemy quản lý DB queries trên Backend.
• Data Sync & Client State: @rocicorp/zero (0.26.2), Zustand (5.0.9), TanStack Query (5.90.7).
• Background Tasks: Queue và Workers bằng Celery (5.5.3) trên Redis (5.2.1).
• AI/LLM Ecosystem: Xử lý luồng bằng LangChain (1.2.13), gọi API bằng LiteLLM (1.83.0), tìm kiếm bằng Elasticsearch (9.1.1).
• Data Processing/Scraping: Trích xuất file bằng Unstructured (0.18.31) / Docling (2.15.0), Scraping qua Playwright (1.50.0).

Language-Specific Rules

1. Python (Backend)

• Type Hinting: Bắt buộc sử dụng Strict Type Hints cho tất cả các function, endpoint signature và dataclasses/pydantic models. Tận dụng syntax mới của Python 3.12+ (ví dụ: dùng dict | None thay vì Optional[Dict]).
• Concurrency (Async/Await): Bắt buộc dùng async def cho các I/O-bound operations (Database calls bằng asyncpg, gọi LLM APIs bằng LiteLLM). Code nào CPU-bound hoặc dùng thư viện sync thì đẩy vào background task (Celery) hoặc thread pool.
• Dependency Injection: Tận dụng tối đa fastapi.Depends() cho các logic như xác thực, cấp phát Database Session, cấu hình.
• Naming Conventions:
  • snake_case cho variables, functions, module files và methods.
  • PascalCase cho Classes và Pydantic Models.
  • UPPER_SNAKE_CASE cho constants và environment variables.
• Docstrings: Sử dụng chuẩn Google docstrings cho các Public Functions và Classes, mô tả rõ Parameters (Args:) và Return values (Returns:).
• Linting & Formatting: Tuân thủ ruff cho cả linting và formatting. Ghi đè các rules theo cấu hình trong pyproject.toml.

2. TypeScript/JavaScript (Web Frontend & Extension)

• Strict Typing: Không sử dụng any trừ trường hợp bất khả kháng. Luôn define interface hoặc type rõ ràng, đặc biệt với các props truyền qua Component hay Data Model lấy từ APIs/DB.
• Next.js Paradigms: Mặc định coi mọi component React là Server Components. Chỉ thêm "use client" trên đầu file khi component đó bắt buộc phải sử dụng Browser API, Client State (Zustand) hoặc Effects (useEffect).
• Naming Conventions:
  • camelCase cho variables, functions, methods, instances, và hooks (ví dụ: useAuth).
  • PascalCase cho React Components, Types, Interfaces, và Classes.
  • UPPER_SNAKE_CASE cho global constant configs.
• File & Folder naming:
  • kebab-case cho tên file và thư mục thông thường (VD: user-profile.tsx, components/ui).
  • Đối với Next.js App Router rules: Tuân thủ cấu trúc framework như page.tsx, layout.tsx, route.ts.
• Biome Formatting & Linting (biome.json):
  • Thụt lề bằng tab (với hiển thị thụt lề bằng 2 spaces).
  • Sử dụng dấu ngoặc kép "double" cho chuỗi và thuộc tính JSX.
  • Bắt buộc chấm phẩy ở cuối dòng (semicolons: "always").
  • Bật các cảnh báo kiểm tra Exhaustive Dependencies cho React hooks.
• Comments: Prefer các bình luận giải thích TẠI SAO (Why) thay vì LÀM GÌ (What). Sử dụng TSDoc syntax (/** ... */) cho việc ghi chú function signature, component interface.

Framework & Library Rules

1. Next.js 16 (App Router) & React

• Data Fetching: Ưu tiên dùng Server Components (async/await trực tiếp trong component) cho dữ liệu tải ở lần đầu tiên (Initial Load) để tối ưu hiển thị.
• Client Side Fetching & Mutations: Sử dụng React Query (TanStack Query) cho các thao tác gọi API phía client cần quản lý cache, loading, error state.
• Server Actions: Sử dụng Server Actions cho các form submission trên Server Components. Với WebApp cần tính realtime/phức tạp, có thể trực tiếp gọi REST APIs của FastAPI (hoặc thông qua @rocicorp/zero).

2. FastAPI (Backend)

• Route Organization: Phải chia nhỏ API endpoints thành các module APIRouter (ví dụ trong app/routers/ hay app/api/). Tuyệt đối không nhét chung tất cả logic vào tệp main.py.
• Validation: Sử dụng triệt để các Pydantic Models nhận request object để tự động validate input.
• Error Handling: Nếu có lỗi, bắt buộc trả về bằng lệnh raise HTTPException(status_code=..., detail=...). Không bắt lỗi rồi return thành công (HTTP 200) kèm thêm key "error": true.

3. Database & Real-Time Sync

• Backend Migrations: Mọi sự thay đổi về Cấu trúc bảng Database phải thông qua công cụ Migration Engine Alembic (cho SQLAlchemy). Không chạy lệnh ALTER TABLE trực tiếp.
• Local-First Sync: Các state/dữ liệu realtime trên giao diện cần tận dụng @rocicorp/zero. Khi làm việc với Zero Database, hãy tuân theo schema định nghĩa sẵn dành riêng cho Zero Client.
• Client State (Theo mức độ):
  • Server State (Dữ liệu từ API): Quản lý bởi TanStack Query hoặc @rocicorp/zero.
  • Global UI State (VD: Theme, Tooltip, Panel mở rông): Quản lý qua Zustand hoặc Jotai.
  • Local Component State: Sử dụng useState.

4. Styling (TailwindCSS 4)

• Convention: Tuân thủ Utility-First CSS. Không viết custom CSS class trong file index.css trừ phi xử lý animation phức tạp hoặc theme variables.
• Responsive Design: Thiết kế theo luồng Mobile-First. Class mặc định dùng cho màn hình di động, dùng tiếp các prefix sm:, md:, lg: để build giao diện cho PC / Tablet.

Critical Implementation Rules

Testing Rules

1. Backend Testing (Python/FastAPI)

• Framework: Sử dụng pytest làm test runner chính cho cả Unit Tests và Integration Tests.
• Coverage: Bắt buộc phải có test bao phủ các API Endpoints (sử dụng TestClient) và các Core Services quan trọng (VD: RAG Pipeline, Sync logic).
• Fixtures & Mocking:
  • Khai thác pytest.fixture để chia sẻ database sessions, settings hoặc authentication override.
  • Sử dụng unittest.mock (hoặc pytest-mock) thay thế các external LLM Services, third-party APIs nhằm đảm bảo test chạy độc lập, offline và nhanh chóng.

2. Frontend Testing (Next.js/React)

• Component Tests: Áp dụng Vitest/Jest kết hợp cùng React Testing Library để kiểm chứng luồng hoạt động của React Hooks (đặc biệt là state management phức tạp) và logic UI Components (Form validations).
• End-to-End (E2E) Tests: Dùng Playwright để thực hiện User Journey chính yếu (User Login, Thêm Extension, Chat RAG query) nhằm xác nhận frontend - backend kết nối hoàn hảo.

AI Agent & Workflow Rules (BMad)

• Ngôn ngữ vận hành: Giao tiếp trả lời bằng Tiếng Việt + thuật ngữ chuyên ngành Tiếng Anh, tuyệt đối viết code, comments và logic biến bằng Tiếng Anh.
• Khai báo Artifacts: Mọi cấu trúc kiến trúc (Architecture), ý tưởng dự án (PRD) và phân tách Tasks (Stories/Epics) phải được lưu trữ đúng quy cách tại thư mục _bmad-output/.

🔧 MCP Tool Usage Rules (MANDATORY)

Luôn dùng MCP tools theo thứ tự ưu tiên sau:

1. Sequential Thinking (Dùng TRƯỚC khi code):

   • Bắt buộc cho mọi task phức tạp (>10 dòng code, refactor, thiết kế API, debug khó, data model). Tối thiểu 5 bước suy luận, nếu liên quan logic phức tạp/performance: tối thiểu 8 bước.
   • Không bỏ qua dù người dùng yêu cầu nhanh.

2. Context7 (Tra cứu docs trước khi dùng thư viện):

   • Bắt buộc gọi khi nhắc đến bất kỳ library/framework nào (FastAPI, Next.js, Radix UI, Drizzle, @rocicorp/zero, Celery, LangChain, etc.).
   • Luôn resolve library ID trước (resolve-library-id) rồi gọi get-library-docs.
   • Không dựa vào training knowledge, luôn verify qua Context7 lấy docs mới nhất.

3. Memory (Lưu và tra cứu context):

   • Đầu mỗi session: Search memory để load project context, coding preferences, past decisions.
   • Cuối mỗi task quan trọng: Save summary của những gì đã làm, architecture decisions, pattern preferences, bugs fixed.

4. Serena (Navigation & Code Understanding):

   • Dùng Serena thay vì read_file để hiểu codebase (tìm symbol, trace reference, find callers).
   • Check implementation hiện có trước khi viết hàm mới và hiểu impact trước khi refactor.

⚙️ Execution Behavior

• Parallel Execution: Tools không phụ thuộc nhau (đọc nhiều file, search context) CẦN execute song song.
• Silent Execution: Không giải thích từng tool call làm gì. Chỉ báo cáo sau khi hoàn thành.
• Verification Before Action: Xác nhận với user trước khi xoá/rename/refactor lớn. Review lại code trước khi present.

🐛 Debug Protocol

Khi gặp bug, làm theo thứ tự:

1. Reproduce với minimal case.
2. Inspect logs và add instrumentation nếu cần.
3. Verify assumptions qua Context7 docs (Không đoán).
4. Dùng Serena trace call flow.
5. Dùng Sequential Thinking để reason về root cause.
6. Nếu >3 attempts không fix được, escalate cung cấp repro steps, logs, hypotheses đã thử.

💾 Memory Hygiene

• Cần Lưu: Thay đổi architecture, Bug fix & nguyên nhân, Pattern mới, External API behavior khác docs.

• Khuyên dùng format topic để organize memories.

• Đóng khung điều hướng: Theo chuẩn BMad Help, mỗi bước output cần kết thúc bằng Terminal Navigation [A] (Advanced), [P] (Party Mode/Review), [C] (Continue).