Chrome Extension hỗ trợ người dùng học chủ động từ một video YouTube: đọc transcript, tạo quiz/flashcard, chấm kết quả, xác định phần đã hiểu và phần cần cải thiện, sau đó đưa người dùng về đúng timestamp nên xem lại.
Luồng nghiệm thu chính:
YouTube video
-> Chrome Extension
-> Lấy transcript có timestamp
-> Local RAG Service xử lý transcript
-> Embedding + ChromaDB cục bộ
-> AI Gateway trên Vercel
-> Gemini tạo quiz/flashcard từ context RAG
-> Người dùng làm bài
-> Chấm điểm và phân tích chủ đề
-> Gợi ý timestamp cần xem lại trong chính video
V1 bao gồm:
PersistentClient lưu chunk, embedding và timestamp trên máy người dùng.V1 không bao gồm:
┌──────────────────────────────┐
│ YouTube page │
│ Video ID + transcript + time │
└──────────────┬───────────────┘
│
v
┌──────────────────────────────┐ ┌──────────────────────────┐
│ Chrome Extension │──────>│ AI Gateway (Vercel) │──────> Gemini API
│ UI, scoring, playback │ │ Validate, limit, retry │
└──────────────┬───────────────┘ └──────────────────────────┘
│ localhost
v
┌──────────────────────────────┐
│ Local RAG Service │
│ Process, embed, retrieve │
└──────────────┬───────────────┘
│
v
┌──────────────────────────────┐
│ ChromaDB PersistentClient │
│ Chunk + embedding + timestamp│
└──────────────────────────────┘
Gemini API key chỉ tồn tại trong biến môi trường của AI Gateway, không nằm trong source, bundle hay manifest của extension. Extension chỉ gửi loại tác vụ và dữ liệu đầu vào đã được giới hạn; gateway tự dựng prompt/schema tin cậy rồi gọi Gemini. Local RAG Service vẫn chạy trên máy người dùng và không nhận secret của gateway. File ChromaDB không được upload, nhưng các đoạn transcript đã retrieval sẽ đi qua gateway tới Gemini để sinh nội dung; vì vậy luồng AI không phải on-device hoàn toàn.
.
├── extension/ # Thành viên 1; riêng src/ai-content do TV3 sở hữu
│ ├── public/
│ │ └── icons/
│ └── src/
│ ├── background/ # Service worker, lifecycle extension
│ ├── content/ # Tích hợp trang YouTube
│ ├── sidebar/ # React shell, hooks, view và UI dùng chung
│ ├── features/
│ │ ├── quiz/ # Giao diện làm bài
│ │ ├── flashcard/ # Giao diện flashcard
│ │ └── learning-assessment/ # Hiển thị kết quả và chỗ cần xem lại
│ ├── integrations/
│ │ ├── local-service/ # HTTP client tới localhost
│ │ ├── ai-gateway/ # HTTP client tới AI Gateway, không chứa secret
│ │ ├── youtube/ # Bridge tới content script/tab YouTube
│ │ └── learning/ # Điều phối retrieval, prompt và mapping
│ ├── ai-content/ # TV3: request, mapping, validate AI output
│ ├── types/ # Contract API, message và UI
│ └── tests/ # Unit/integration test của extension
├── gateway/ # Vercel Functions gọi Gemini phía server
│ ├── api/ # Health và generate endpoints
│ └── src/ # Config, validation, prompt/schema và provider client
├── local-rag-service/
│ ├── app/
│ │ ├── core/ # TV2: config, lifecycle, health
│ │ ├── transport/ # TV2: endpoint/DTO adapter trên localhost
│ │ ├── transcript/ # TV3: làm sạch và chuẩn hóa transcript
│ │ ├── chunking/ # TV3: chunk, overlap, timestamp
│ │ ├── embedding/ # TV3: model và batch embedding
│ │ ├── vector_store/ # TV3: ChromaDB schema/adapter
│ │ ├── retrieval/ # TV3: search, filter, context builder
│ │ └── assessment/ # TV3: topic/strength/weakness/timestamp
│ └── tests/
│ ├── service/ # TV2
│ └── rag/ # TV3
├── shared/
│ └── contracts/ # Schema giao tiếp; thay đổi cần review chéo
├── scripts/ # TV2: setup/start/stop/clear local data
├── tests/
│ └── e2e/ # TV4: integration và end-to-end
├── docs/
│ ├── architecture/ # Thiết kế đã được nhóm duyệt
│ ├── project-management/ # Kế hoạch và phân công công việc
│ └── testing/ # TV4: test plan/report/evidence
├── outputs/ # Kết quả làm việc tạm; không commit
├── work/ # Công cụ và file trung gian tạo tài liệu
├── CONTRIBUTING.md # Quy trình branch, commit và review
├── OWNERS.md # Quyền sở hữu theo thư mục
└── .gitignore
Các thư mục thể hiện ranh giới runtime và quyền sở hữu hiện tại. Không đổi công nghệ hoặc hợp đồng dùng chung một cách đơn phương.
| Thành viên | Phạm vi chính | Không tự thay đổi |
|---|---|---|
| Thành viên 1 — Extension Frontend | extension/, trừ extension/src/ai-content/ |
Pipeline RAG, ChromaDB schema, prompt và assessment logic |
| Thành viên 2 — Local Service & Integration | local-rag-service/app/core/, transport/, local-rag-service/tests/service/, scripts/ |
Chunking, embedding, retrieval và ChromaDB schema |
| AI Gateway — Backend dùng chung | gateway/ |
UI extension, Local RAG; không mở contract nhận prompt/model/schema tùy ý |
| Thành viên 3 — AI/RAG Lead | extension/src/ai-content/, các module AI/RAG trong local service, local-rag-service/tests/rag/ |
UI/lifecycle extension và khung vận hành service ngoài giao diện đã thống nhất |
| Thành viên 4 — QA/Integration | tests/e2e/, docs/testing/ |
Source của thành viên khác; lỗi được sửa qua issue/PR của owner |
Chi tiết quyền sở hữu và điểm cần review chéo nằm trong OWNERS.md.
main.feat/tv1-sidebar, feat/tv2-health-check, feat/tv3-rag-retrieval, test/tv4-gateway-e2e.README.md, CONTRIBUTING.md, OWNERS.md, manifest, file dependency/lock, schema trong shared/contracts/ và tài liệu kiến trúc..env, dữ liệu ChromaDB hoặc transcript của người dùng.Quy trình đầy đủ xem tại CONTRIBUTING.md.
Trước khi hai phía triển khai song song, nhóm cần chốt schema trong shared/contracts/ cho các đối tượng tối thiểu:
videoId, text, startSec, endSec.Mọi thay đổi schema phải cập nhật contract trước, sau đó mới cập nhật producer và consumer trong cùng pull request hoặc các pull request được liên kết.
Lệnh cài đặt, build và chạy thật được duy trì tại:
Không ghi lệnh giả vào README. Mỗi lệnh chỉ được thêm sau khi đã chạy thử trên một máy mới hoặc môi trường sạch.
videoId.Kiến trúc runtime hiện hành: docs/architecture/ai-gateway.md. Các tài liệu kế hoạch/SDS cũ được giữ làm hồ sơ lịch sử và có thể vẫn mô tả kiến trúc OAuth; không dùng chúng làm hướng dẫn cấu hình runtime hiện tại.
docs/project-management/plan.txt.docs/project-management/phan_cong_chi_tiet.txt.docs/architecture/*.docx và bản sao SDS_*.docx ở thư mục gốc.docs/testing/.