bindbox-game/.planning/codebase/ARCHITECTURE.md

Architecture

Overview

Bindbox Game follows a layered monolith architecture pattern built with Go and the Gin HTTP framework. The application serves as a backend for a blind box / lottery game platform with both a WeChat Mini Program client and a Vue 3 admin panel.

Architectural Pattern

Layered Architecture (Handler → Service → Repository)

HTTP Request
    ↓
[Router] → route matching + middleware (auth, RBAC, blacklist)
    ↓
[API Handler] → request parsing, validation, response formatting
    ↓
[Service Layer] → business logic, orchestration
    ↓
[Repository Layer] → GORM-based data access (MySQL read/write split)
    ↓
MySQL (Master/Slave)

Key Layers

1. Router Layer (internal/router/)

• router.go — Single file defining all routes via NewHTTPMux()
• Routes organized into groups:
  • /api/internal — Internal service calls (X-Internal-Key auth)
  • /api/admin — Admin panel (JWT + RBAC)
  • /api/app — Mini Program public endpoints (no auth)
  • /api/app (auth group) — Mini Program authenticated endpoints
  • /api/public — Public livestream endpoints (access code auth)
  • /api/pay — WeChat Pay callbacks (no auth)

2. Interceptor / Middleware Layer (internal/router/interceptor/)

• admin_auth.go — JWT token verification for admin users
• admin_rbac.go — Role-based access control with action-level permissions
• app_auth.go — App user token verification
• blacklist.go — Douyin user blacklist checking
• interceptor.go — Base interceptor struct with shared dependencies

3. API Handler Layer (internal/api/)

Organized by domain:

• admin/ — Admin panel handlers (largest, ~30+ files)
• activity/ — Lottery/game activity handlers
• app/ — Store, product, banner, category handlers
• game/ — Game ticket and minesweeper handlers
• pay/ — Payment handlers
• user/ — User management, orders, addresses
• task_center/ — Task center handlers
• common/ — Shared utilities (upload, openid)
• public/ — Public livestream handlers
• internal/ — Internal API handlers (Nakama integration)

4. Service Layer (internal/service/)

Business logic organized by domain:

• activity/ — Activity CRUD, lottery processing, matching game, settlements, strategy pattern for draw types
• admin/ — Admin user management, login
• user/ — User management, orders, points, coupons, inventory, shipping, synthesis
• order/ — Order processing
• game/ — Game ticket management, minesweeper
• douyin/ — Douyin order sync, reward dispatching
• task_center/ — Task definitions, progress tracking, worker
• product/ — Product management
• finance/ — Financial operations, ledger
• channel/ — Marketing channel management
• title/ — User title/badge system
• banner/, sysconfig/, common/, snapshot/, recycle/, synthesis/, livestream/

5. Repository Layer (internal/repository/mysql/)

• mysql.go — Database connection management (read/write split via Repo interface)
• plugin.go — GORM plugins
• model/*.gen.go — Generated GORM models (do not edit)
• dao/*.gen.go — Generated GORM DAOs (do not edit)
• task_center/models.go — Task center specific models
• test_helper.go, testrepo_sqlite.go — Test infrastructure

Entry Point

main.go initializes all infrastructure in order:

1. Config (Viper/TOML)
2. OpenTelemetry
3. MySQL (master + slave)
4. Logger (Zap-based with rotation)
5. Redis
6. HTTP server (Gin)
7. Background workers (settlement, expiration, order sync, dynamic config)
8. Graceful shutdown handler

Data Flow

Typical API Request Flow

Client → Gin Router → Middleware Chain → Handler → Service → Repository → MySQL
                                                      ↓
                                                   Redis (cache, locks)

Background Task Flow

Scheduler (cron) → Service Method → Repository → MySQL
                       ↓
                   External API (WeChat, Douyin)

Payment Flow

Client → Preorder API → WeChat Pay API → Client pays → WeChat Callback → Notify Handler → Order Service

Key Design Decisions

Decision	Rationale
Read/write DB split	Performance: heavy reads go to slave, writes to master
GORM code generation	Consistency: models and DAOs auto-generated from schema
Custom core.Context wrapper	Standardized error handling, tracing, session management across all handlers
Strategy pattern for lottery	Different draw types (standard, ichiban) share interface but have different logic
Background workers in main process	Simplicity: no separate worker binary, uses goroutines
JWT with hash verification	Security: stored token hash prevents concurrent sessions

Cross-Cutting Concerns

• Logging: Zap-based with file rotation (internal/pkg/logger/)
• Tracing: OpenTelemetry integration (internal/pkg/otel/)
• Error Codes: 5-digit system in internal/code/ (service level + module + specific)
• Alerts: Alert notification system (internal/alert/)
• Metrics: Prometheus metrics (internal/metrics/)

External Service Boundaries

The application integrates with multiple external services through dedicated packages in internal/pkg/:

• WeChat Mini Program API (wechat/, miniprogram/)
• WeChat Pay v3 API (pay/)
• Douyin/TikTok API (douyin/)
• Aliyun SMS (sms/)
• Tencent COS (object storage)
• OpenTelemetry collector

---

Generated: 2026-03-21