docs / full-project-flow
Source snapshot · 2026-06-12

Full project flow map.

Bản đồ từ HTTP entrypoint tới domain service, database, Redis queue, worker và external provider. Route comment hoặc module không được mount không được tính là API hiện hành.

126route declarations
19mounted route groups
12queue names
10worker implementations
01

Request lifecycle chung

sync path

Mọi endpoint hiện hành nằm dưới /api/v1. HLS là ngoại lệ về body parser vì cần raw body để xác minh chữ ký.

ClientHTTP · Bearer token · body/query/params
App middlewareHelmet · CORS · compression · logger
Global router/api/v1 · rate limiter · mounted group
Route middlewareauthorization · role · Zod validate
Domaincontroller · service · repository
ResultPrisma/Redis/job/provider · response envelope
02

Route coverage

126 / 126

Các nhóm dưới đây được mount thật trong src/routes/index.ts. Catalog chi tiết chứa method, path, auth, handler và source file cho từng endpoint.

/admin14 /ai1 /auth13 /circle35 /circle-ai1 /health1 /me6 /message-groups6 /museum2 /notification5 /posts22 /pusher1 /quests2 /search3 /topic2 /upload2 /user4 /users4 /webhooks2
Source of truth: mở catalog 126 route. Chạy npm run docs:routes để sinh lại catalog từ TypeScript AST.
03

Luồng nghiệp vụ end-to-end

15 flow families

Mỗi thẻ gom các endpoint cùng một hành vi và chỉ ra phần xử lý sau HTTP response khi có queue hoặc realtime side effect.

Identity & sessioncurrent
  1. Register/login và kiểm tra username/email.
  2. Hash password/refresh token, phát JWT pair.
  3. Verify/forgot password enqueue email worker.
  4. Logout blacklist access token trong Redis.
full flow13 routes
Profile & social graphcurrent
  1. Đọc profile/mention, karma và badge.
  2. Follow/unfollow, followers/following.
  3. Gửi, hủy, chấp nhận friend request.
  4. Cập nhật counter/notification liên quan.
full flow14 routes
Create postcurrent
  1. Zod validate content/topic/media.
  2. Service tạo post và relation trong transaction.
  3. Enqueue Pinecone indexing.
  4. Ghi action log và notification khi cần.
full flowpost API
Post interactioncurrent
  1. Reply/quote/repost kiểm tra visibility và policy.
  2. Like state cập nhật atomic trong Redis.
  3. Like worker sync event về DB.
  4. Reply/mention/like tạo grouped notification.
interactionlike incident
Post lifecycle & moderationcurrent
  1. Edit/delete yêu cầu ownership.
  2. Delete là soft delete và bump cache version.
  3. Save/hide lưu state theo user.
  4. Report đi qua evaluation/admin moderation.
visibilitysavehide/report
Feed & content readscurrent
  1. News feed và profile post dùng cursor pagination.
  2. Lọc hidden/deleted và visibility.
  3. Hydrate author, media, topic và interaction state.
  4. Cache key/version được bump sau mutation.
newsfeedpost module
Search & discoverycurrent
  1. MySQL/Prisma phục vụ tìm kiếm post/user/topic.
  2. Post creation ghi dữ liệu trực tiếp vào MySQL.
  3. Mixedbread sinh embedding.
  4. Pinecone trả semantic similar posts.
search flow3 routes
Circle membershipcurrent
  1. Create/list/detail circle và membership.
  2. Invitation/join request có response lifecycle.
  3. Owner/admin quản lý role, kick và ban.
  4. Circle post/reply áp dụng permission riêng.
circle flow36 routes
Circle HP, EXP & CPRcurrent
  1. Evaluation worker chấm chất lượng circle post.
  2. Ghi quality log, EXP log và energy delta.
  3. Level-up dựa trên rule hiện hành.
  4. CPR/sacrifice dùng karma và restriction policy.
business logicextended flow
Chat & realtimecurrent
  1. Create group, member và message.
  2. Persist message trước khi trigger Pusher.
  3. Client authorize private/presence channel.
  4. Message worker gom unread notification mỗi 3 giây.
Pusher flowchat flow
Grouped notificationscurrent
  1. Event ghi hash/set/zset tạm trong Redis.
  2. Repeat job quét item đến hạn mỗi 5 giây.
  3. Worker tạo NotificationGroup trong DB.
  4. Pusher phát event và API trả unread counters.
realtimebug analysis
Media & webhookscurrent
  1. Multer nhận avatar hoặc tối đa 5 media.
  2. Sharp resize trước khi upload R2.
  3. HLS webhook dùng raw body + signature.
  4. Leonardo callback cập nhật preview image.
HLS flowupload APIwebhooks
Daily quest & action logcurrent
  1. Admin định nghĩa quest và action.
  2. User action service ghi event có target/metadata.
  3. Quest service tính progress theo ngày.
  4. Claim kiểm tra completion rồi cộng karma.
quest flow2 routes
Admin & moderationcurrent
  1. Admin login riêng, route còn lại cần bearer + role.
  2. List/ban/unban user, auto-remove timed ban.
  3. Review report và chạy evaluation report.
  4. Stats, trending hashtag và daily quest CMS.
admin flowstatus14 routes
AI generation & evaluationmulti-provider
  1. AI endpoint tạo image/caption theo service hiện hành.
  2. Circle AI sinh markdown response.
  3. Evaluation worker gọi AI scoring.
  4. Embedding dùng Mixedbread, vector lưu Pinecone.
AI flowAI APImodule
04

Queue và worker coverage

11 names · 9 workers

Không phải mọi tên queue đều có worker riêng: likes_events là Redis list do like worker drain; friend-request scheduling hiện dùng message queue.

Queue / structureConsumerMục đích
email_queueemail workerVerify email, forgot password, invitation email.
bloom_queuebloom workerCập nhật Redis Bloom cho username/email.
pinecone_queuepine workerSinh embedding và upsert Pinecone.
like_queue + likes_eventslike workerDrain event Redis, sync DB và phát like notification.
notificationnotification workerBatch reply/mention notification mỗi 5 giây.
message_queuemessage workerBatch chat notification mỗi 3 giây.
evaluation_queueevaluate workerChấm post/report, cập nhật quality, HP/EXP và moderation.
delta_hp_queuedelta HP workerTăng/giảm circle energy theo job.
auto_remove_ban_queueauto-remove-ban workerDọn timed ban đã hết hạn.
friend_request_queuekhông có worker riêngConstant/queue được tạo, nhưng scheduler hiện add friend request job vào message queue.
worker operations mapbackground jobsjobs module
05

Known gaps và tài liệu tham khảo

không tính vào route coverage
Các điểm cần phân biệt với API hiện hành:
  • GET /topic đang hoạt động cho search; route list topic cũ trong code đã comment nên không được tính thêm.
  • Docs dưới modules/internal và api/internal.html mô tả endpoint internal cũ, nhưng router internal không được mount trong src/routes/index.ts.
  • friend_request_queue có trong constants/producer nhưng không có worker riêng; initFriendRequest() hiện thao tác trên message queue.
  • Các trang Liquidation Stakes, Emotional Butterfly Effect và Bonus Features là thiết kế/kế hoạch mở rộng, không đồng nghĩa đã có route production.