System Architecture - Search Tool

1. Tech Stack

Thành phần	Công nghệ	Ghi chú
Language	Go 1.21+	—
HTTP Framework	Fiber v2	Fast HTTP dựa trên fasthttp
ORM (MySQL)	GORM	Auto-migration, soft delete
MongoDB Driver	go.mongodb.org/mongo-driver	Document store cho task pool
Cache	Redis (go-redis)	Cache kết quả anchor text
DI Container	uber/dig	Dependency injection
Auth	JWT (golang-jwt/jwt)	Bearer token
Logger	uber/zap + lumberjack	Structured logging, log rotation
Scheduler	Custom scheduler	Cron-based task dispatch

2. Sơ đồ kiến trúc tổng quan

┌─────────────────────────────────────────────────────────┐
│                 Search Tool API                       │
│               (Go + Fiber, port 33003)                │
│                                                         │
│  ┌──────────┐  ┌──────────┐  ┌───────────────────────┐ │
│  │  /api/* │  │ /search/ │  │    /anchor-text/      │ │
│  │  (JWT)   │  │ /anchor- │  │    (Search Token)     │ │
│  │          │  │  text/   │  │                       │ │
│  │ User     │  │  (Search │  │  Anchor Text Handler  │ │
│  │ Server   │  │  Token)  │  │  → MongoDB pool       │ │
│  │ CRUD     │  │  → Mongo │  └───────────────────────┘ │
│  └──────────┘  │  pool    │                            │
│                └──────────┘  ┌───────────────────────┐ │
│                              │    /webhook/* │ │
│                              │  (Webhook Key)        │ │
│                              │  - get-proxy          │ │
│                              │  - update-search-result││
│                              │  - update-anchor-text │ │
│                              └───────────────────────┘ │
│                                                         │
│  ┌─────────────────────────────────────────────────┐   │
│  │         Cron Job (goroutine, mỗi 60s)           │   │
│  │  1. Lấy pending tasks từ MongoDB                │   │
│  │  2. Lấy active servers từ MySQL                 │   │
│  │  3. Phân phối tasks → Worker Servers            │   │
│  └─────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────┘
        │                              │
        ▼                              ▼
┌──────────────┐              ┌──────────────────┐
│    MySQL     │              │    MongoDB       │
│  - users     │              │  - keyword tasks │
│  - servers   │              │  - anchor tasks  │
└──────────────┘              └──────────────────┘
        │
        ▼
┌──────────────┐
│    Redis     │
│  Cache (5m)  │
└──────────────┘
        │
        ▼ (callback)
┌──────────────────────────────────┐
│        Worker Servers            │
│  (external — IP lưu trong MySQL) │
│  Chạy tool search thực tế        │
│                                  │ 
│  POST kết quả về /webhook/...    │
└──────────────────────────────────┘

3. Luồng khởi động ứng dụng

main.go
  │
  ├─ pkg.LoadEnv()                  → Đọc .env vào EnvStruct
  ├─ injection.ProvideComponents()  → Khởi tạo DI container (uber/dig)
  │     ├─ database.Connect()       → Kết nối MySQL + MongoDB
  │     ├─ cache.NewRedisCache()    → Kết nối Redis
  │     └─ NewService() x N         → Đăng ký tất cả services
  ├─ fiber.New()                    → Tạo HTTP server
  ├─ middleware (CORS, Helmet, ErrorHandler, Logger)
  ├─ bootstrap.InitRoutes()         → Đăng ký tất cả routes
  │     └─ cron.RunCron()           → Khởi động goroutine cron
  ├─ socket_bootstrap.NewSocketServer() → Socket.IO
  └─ app.Listen(:PORT)             → Lắng nghe HTTP

4. Dependency Injection

Sử dụng uber/dig — IoC container kiểu constructor injection.

Container
  ├─ EnvStruct (pkg.LoadEnv)
  ├─ database.DbConn (MySQL + MongoDB)
  ├─ cache.RedisCache
  ├─ scheduler.Scheduler
  ├─ user.Service
  ├─ activityLog.Service
  ├─ proxy.Service
  ├─ server.Service
  ├─ keyword.Service
  ├─ keywordPoolTask.Service
  ├─ keywordResult.Service
  └─ anchorText.Service

Các handler gọi injection.Container.Invoke(...) để nhận service đã được inject.

5. Cơ chế phân phối task (Weighted Task Dispatch)

Mỗi 60 giây, cron job thực hiện:

Lấy tasks từ MongoDB có status = Status_New
Lấy servers từ MySQL có is_active = true
Tính trọng số phân phối:
- IsPriority = true → weight 5
- IsPriority = false → weight 2
Phân bổ số task cho mỗi server theo tỷ lệ weight
Cập nhật status → Status_Processing
Gửi task batch đến từng server qua HTTP POST (retry tối đa 3 lần, exponential backoff)
Nếu server xác nhận nhận task → xoá khỏi pool MongoDB

Ví dụ với 2 servers, 70 tasks:
  Server A (priority=true,  weight=5): 70 * 5/7 = 50 tasks
  Server B (priority=false, weight=2): 70 * 2/7 = 20 tasks

7. Cơ chế xử lý kết quả Anchor Text (với Redis cache)

Worker gọi: POST /webhook/update-search-anchor-text/:id?hook_url=<client_url>
                              │
                    API nhận callback
                              │
              ┌───────────────┴────────────────┐
              │                                │
    Có kết quả (anchor_text > 0)?         Không có kết quả
              │                                │
    Save vào Redis (TTL 5m)         searched < 10? → tăng searched, retry
    key: {domain}_{anchor_keys}           searched >= 10? → drop task
              │
    Forward kết quả đến hook_url của client (POST)
              │
    Client confirm (HTTP 2xx)?
              │
    Xoá task khỏi MongoDB pool

--- Cron job check Redis (lần tiếp theo) ---
Task cùng domain đã có cache?
  → YES: Gọi hook_url trực tiếp từ cache, xoá task (không giao cho worker)
  → NO: Giao cho worker bình thường

8. Middleware Stack

Middleware	Route	Mô tả
`cors.New()`	Toàn bộ	CORS headers
`helmet.New()`	Toàn bộ	Security HTTP headers
`ErrorHandler`	Toàn bộ	Chuẩn hoá lỗi thành JSON response
`fiberLogger`	Toàn bộ	HTTP access log
`JWTMiddleware`	`/api/*` (trừ login/register)	Xác thực Bearer JWT
`SearchMiddleware`	`/search/`, `/anchor-text/`	Xác thực API_SEARCH_TOKEN
`WebhookMiddleware`	`/webhook/*`	Xác thực WEBHOOK_KEY

9. Module nội bộ của API (pkg/)

Package	Mô tả
`pkg/env.go`	Load và parse `.env` vào struct `EnvStruct`
`pkg/database`	Kết nối MySQL (GORM) và MongoDB
`pkg/cache`	Redis cache wrapper
`pkg/jwt`	JWT generate và validate
`pkg/middleware`	Tất cả middleware
`pkg/apperror`	Error response builder (BadRequest, NotFound, ...)
`pkg/messages`	Response builder chuẩn hoá
`pkg/validate`	Validator wrapper (go-playground/validator)
`pkg/logger`	Logger wrapper (uber/zap)
`pkg/helper`	Helper utilities (mysql_helper, ...)
`pkg/scheduler`	Scheduler base
`pkg/api/proxy`	Client gọi external proxy API
`pkg/api/search_anchor_text`	DTO + factory cho anchor text task
`pkg/api/search_keyword`	DTO + factory cho keyword task