CẤU TRÚC MÃ NGUỒN (CODE STRUCTURE)#
Codebase được viết chuẩn Typescript hoàn toàn, strict mode. Tổ chức theo mô hình Layered Architecture: Controller -> Service -> Model và nhóm theo Domain-Driven thư mục để module hóa dễ scale.
1. Sơ đồ thư mục#
/src
├── index.ts -> Boot loader/Entrypoint, load config, swagger, setup main Elysia HTTP app
├── config/ -> Config chung của framework, Database mongodb connection options.
├── api/ -> Logic module / Domain chính (các domains sẽ import vào /api/index.ts)
│ ├── index.ts -> Tích hợp các route để mount vào root app
│ ├── search/ -> Scope xử lý Search engine tool
│ │ ├── search.controller.ts -> Routes (GET/POST/DELETE) đón request
│ │ ├── search.service.ts -> Tầng logic update, query Data tới MongoDB (lọc data, locking mutex)
│ │ ├── search.cron.ts -> Background Worker logic: run puppeteer flow, check limits, run browser automation
│ │ ├── search.dto.ts -> Type schema validate các fields body/params Input & Output
│ │ └── search.model.ts -> Schema Collection DB mongo (Typegoose Entity)
│ │
│ ├── search-anchor-text/ -> Scope quét verify anchor element
│ │ ├── (các file controller, service, model và cron tương tự như search)
│ │
│ └── (Lưu ý: /proxy folder hiện không xài nữa, đang dùng Proxy Tool để lấy proxy, setup trong .env
├── utils/ -> Tools tiện ích dùng xuyên suốt app
│ ├── browser_manager/ -> Lớp Wrapper thiết lập Chromium flags, manage instance Puppeteer, human-mouse/ghost cursor tránh bot detection
│ ├── logger.ts -> Cấu hình log của bun cho terminal/file text
│ ├── env.ts -> Validate Strict các Environment Variables
│ ├── error.middleware.ts -> Catch all app errors (try catch wrapper) map response format
│ └── createElysia.ts -> Init các Elysia Server Instance
├── services/ -> Các Services layer 3rd-party hoặc gọi ra External Network
│ └── webhook/ -> Logic API client call POST sang target url client report lúc task finished
├── types/ -> Alias và types globals project
2. Các module quan trọng đối với core workflow#
.dto.ts: Trong môi trường ElysiaJS, DTO đóng 2 vai trò: Vừa validate Input data từ API gọi sang chặt chẽ bằng lib tên TypeBox (t), vừa auto-generate document specs cho Swagger.
.cron.ts: Worker file. Đóng vai trò là executor thực thi script cào dữ liệu chứ không trả thẳng trong HTTP cycle. Quản lý timeout, logic load proxy mới cho process và save state data.
browser_manager: Có áp dụng queue control hạn chế mem leak, chèn extension và override args chrome driver để handle session ổn định, không bypass manual logic.
Ngày cập nhật 2026-03-31 02:21:05