docs / current-system-reference
System reference hiện tại
Trang này là bản đồ ngắn gọn của code đang chạy tại ngày 12/06/2026. Khi tài liệu lịch sử mâu thuẫn với trang này, hãy kiểm tra route, DTO và service trong source; source code là nguồn sự thật cuối cùng.
126route declarations
41Prisma models
10workers
12queue names
Request lifecycle
Express middleware
Global rate limit
Module router
Controller + service
Response/error envelope
| Giai đoạn | Code | Hành vi |
|---|---|---|
| App middleware | src/app.ts | Helmet, CORS, compression, Morgan, JSON/urlencoded parser, logger và response helper. |
| HLS exception | /api/v1/webhooks/hls | Raw JSON body được mount trước express.json() để verify chữ ký. |
| API boundary | app.use('/api/v1', apiLimiter, router) | Mọi route bên dưới đều đi qua global limiter. |
| Authorization | src/middlewares/auth.ts | Verify Bearer JWT, Redis blacklist, user tồn tại và trạng thái không bị BANNED. |
| Validation | src/middlewares/validate.ts | Zod parse body/params/query; query đã parse nằm ở req.query_parsed. |
| Success envelope | res.success / res.paginate | { success: true, message?, data?, pagination? }. |
| Error envelope | errorHandler | { success: false, message?, errors?, errorCode? }; map Prisma P2002/P2025/P2003. |
HTTP module map
| Prefix | Module | Auth boundary | Ghi chú |
|---|---|---|---|
/docs | Swagger UI | Public | OpenAPI document được ghép từ module swagger files. |
/admin | Admin | Login public; phần còn lại JWT + ADMIN role | User moderation, report, stats, hashtag và daily quest. |
/auth | Auth | Mixed | Profile, me, logout và resend verify cần JWT. |
/posts | Post | Public reads trước router.use(authorization) | Write/interactions protected; judge-status hiện trả placeholder. |
/circle | Circle | Toàn bộ protected | Circle domain lớn nhất, gồm management và gamification. |
/circle-ai | Circle AI | Protected | Generate markdown response cho circle workflow. |
/users | Public user | Profile/mention public; karma/badge protected | Public profile route phải nằm trước auth boundary. |
/user | Follow | Reads public, writes protected | Follow toggle và legacy friend-request route. |
/me | Current user | Toàn bộ protected | Follower và friend-request lifecycle. |
/message-groups | Chat | Mỗi route protected | Persistence + Pusher + message notification worker. |
/notification | Notification | Toàn bộ protected | Grouped notification và unread counters. |
/search | Search | Toàn bộ protected | Search index tên search, hydrate record từ Prisma. |
/upload | Upload | Media protected; avatar hiện public | Avatar thiếu authorization là hành vi code hiện tại, cần cân nhắc security. |
/webhooks | Webhooks | Provider verification | HLS signature và Leonardo callback key. |
/ai | AI | Toàn bộ protected | HTTP route tạo image; scoring/report chạy nội bộ qua worker. |
/topic, /quests, /museum, /pusher, /health | Supporting HTTP modules | Tùy module | Xem API page tương ứng. |
Module hỗ trợ không mount route riêng
| Module | Trách nhiệm | Được dùng bởi |
|---|---|---|
| access-control | Role, permission, user-role và middleware kiểm tra quyền. | Auth, admin, circle. |
| anti-spam | Lưu/đọc giới hạn hành vi user theo ngày. | Post/circle policy. |
| jwt | Sign/verify access-refresh token pair. | Auth middleware và auth service. |
| limit-action | Khóa hành động AI khi user vượt quota. | AI service. |
| mixed-bread + pinecone | Embedding và vector similarity. | Post semantic search/index worker. |
| report | Tạo report và enqueue AI evaluation. | Post + admin. |
| user-action-log | Audit hành động, quest progress và AI quota. | Post, circle, quest, AI. |
| user-restriction | Restriction theo user/type/expiry. | Circle và moderation policies. |
| job | Producer cho email, index, vector, like, notification, evaluation, HP và ban. | Nhiều domain service. |
Queue và worker
| Queue | Worker hiện có | Mục đích |
|---|---|---|
email_queue | email.worker | Verify, forgot-password và invitation email. |
bloom_queue | bloom.worker | Redis Bloom username/email. |
pinecone_queue | pine.worker | Mixedbread embedding và Pinecone upsert. |
like_queue + likes_events | like.worker | Đồng bộ like state và phát notification count. |
notification | notification.worker | Flush grouped reply/mention/like notification. |
message_queue | message.worker | Flush realtime chat notification. |
evaluation_queue | evaluate.worker | AI score circle post và evaluate report. |
delta_hp_queue | delta-hp.worker | Điều chỉnh circle HP theo repeat job. |
auto_remove_ban_queue | auto-remove-ban.worker | Tự gỡ user ban hết hạn. |
friend_request_queue | Không có worker riêng | Được producer khai báo; cần xác nhận consumer trước khi phụ thuộc. |
Công nghệ thực tế
| Nhóm | Stack hiện tại |
|---|---|
| Runtime/API | Node.js, TypeScript 5.8, Express 5.1, Zod 3.25. |
| Database | Prisma 7.8, @prisma/adapter-mariadb, MySQL/MariaDB. |
| Async/cache | Redis 5 client, ioredis, Redis Bloom, BullMQ 5.76. |
| Search/vector | Prisma, Mixedbread AI, Pinecone. |
| AI | OpenRouter SDK/provider, Groq, Google GenAI dependency, Leonardo provider. |
| Media/realtime | Cloudflare R2 qua AWS S3 SDK, Sharp, HLS, Pusher. |
| Operations | Docker multi-stage, Nginx, API + worker container. |
Các điểm chưa hoàn thiện cần ghi rõ khi tích hợp:
AuthService.updateProfile() hiện trả cờ giả lập; validateResetPasswordToken() luôn trả valid; PostService.getJudgeStatus() trả pending placeholder; avatar upload chưa có authorization; Swagger vẫn có tag Internal dù router không mount internal module.