Kiến trúc tổng thể của Threads API v2

Tổng quan kiến trúc

Threads API v2 là modular monolith: một app Express 5 duy nhất nhưng chia domain thành module rõ ràng. Request đi từ Express router đến controller, service, repository, rồi database hoặc provider ngoài.

Quyết định quan trọng nhất là tách tác vụ nặng sang BullMQ worker. Nhờ đó register không phải đợi email/index search hoàn tất, post không phải đợi embedding xong, và notification có thể gom nhiều event thành một push.

Snapshot 12/06/2026: TypeScript 5.8, Express 5.1, Prisma 7.8 với MariaDB adapter, 41 Prisma models, 9 worker implementations và 11 queue names. Xem system reference hiện tại để biết route prefix và các stub đang tồn tại.

Sơ đồ kiến trúc

Màu cam là API server, màu xanh là worker xử lý phần nặng sau response.

Giải thích từng thành phần

Client

Frontend/mobile gọi HTTP và Pusher.

Express API

Validate, auth, business service, response JSON.

MySQL/Prisma

Nguồn dữ liệu bền vững.

Redis/BullMQ

Cache, queue, blacklist, Bloom filter, debounce.

Workers

Email/vector/notification/AI/like sync.

External APIs

R2, HLS, OpenRouter, Mixedbread, Pinecone, Pusher.

Luồng request điển hình

Browser gửi request đến /api/v1. apiLimiter chạy trước router. Nếu route cần login, authorization verify JWT, kiểm tra blacklist Redis và user status trong DB. Controller gọi service; service validate rule nghiệp vụ, gọi repository/Prisma hoặc enqueue worker.

Điểm kết nối với hệ thống ngoài

Hệ thống ngoài	Giao thức	Mục đích	Được gọi khi nào	Timeout/SLA
Redis	TCP	Cache, queue, Bloom, blacklist	Boot, auth, post, jobs	[CẦN XÁC NHẬN]
MySQL/MariaDB	TCP	Database chính	Mọi repository	[CẦN XÁC NHẬN]
Pinecone	HTTPS SDK	Vector search	Post embedding/search	[CẦN XÁC NHẬN]
OpenRouter	HTTPS SDK	AI scoring/report	Evaluation worker	[CẦN XÁC NHẬN]
Cloudflare R2	S3 API	Image upload	Upload service	[CẦN XÁC NHẬN]
HLS	HTTPS + webhook	Video upload/status	Upload videos/webhook	[CẦN XÁC NHẬN]
Pusher	HTTPS/WebSocket	Realtime events	Message/notification/report	[CẦN XÁC NHẬN]

Quyết định kiến trúc

Vấn đề	Phương án đã cân nhắc	Phương án đã chọn và lý do	Hệ quả / trade-off
Request không bị chậm bởi tác vụ nặng	Xử lý sync hoặc queue	Queue bằng BullMQ/Redis để response nhanh	Có eventual consistency
Tách domain	Microservices hoặc modular monolith	Modular monolith để đơn giản deploy nhưng rõ boundary	Có thể phụ thuộc chéo nếu không kiểm soát
Search	Query DB trực tiếp hoặc index riêng	MySQL + Pinecone	Text search phụ thuộc khả năng query của database
Auth session	JWT stateless hoặc DB session	JWT access + refresh token DB hash	Cần Redis blacklist khi logout