moicle 1.3.1 → 1.4.0

package/assets/architecture/go-backend.md

@@ -1,464 +1,867 @@
 # Go Backend Architecture
 
-> Production-grade Clean Architecture with Modular Design
+> Production-grade DDD with Hexagonal Architecture for Go + Gin
 
-## Project Structure
+**Prerequisite:** Read `ddd-architecture.md` first. This doc shows how DDD maps to Go.
+
+## Tech Stack
+
+| Component | Technology |
+|-----------|------------|
+| Framework | Gin |
+| ORM | GORM |
+| Database | MySQL/PostgreSQL |
+| Cache | Redis |
+| Queue | Asynq |
+| Auth | Firebase Auth |
+| CLI | Cobra |
+| gRPC | google.golang.org/grpc |
+| Storage | AWS S3 / Cloudflare R2 |
+| Real-time | SSE + Redis pub/sub |
+
+---
+
+## DDD Directory Structure
 
 ```
-{project}/
-├── cmd/
-│   ├── api/
-│   │   ├── main.go                   # Entry point (HTTP + gRPC + SSE)
-│   │   └── router.go                 # Route definitions & middleware
-│   └── background/
-│       ├── main.go                   # CLI entry (Cobra)
-│       ├── commands/                 # CLI subcommands
-│       │   ├── consumer.go           # Task consumer
-│       │   ├── scheduler.go          # Task scheduler
-│       │   └── sync.go               # Sync command
-│       └── consumers/                # Task handlers (Asynq)
-│           ├── notification.go
-│           └── cleanup.go
-├── internal/
-│   ├── config/
-│   │   └── config.go                 # App configuration
-│   ├── middleware/
-│   │   ├── auth.go                   # Auth middleware + caching
-│   │   ├── admin_auth.go             # Admin auth
-│   │   ├── cors.go                   # CORS
-│   │   ├── logger.go                 # Request logging
-│   │   ├── recovery.go               # Panic recovery
-│   │   └── api_key.go                # API key validation
-│   ├── grpc/                         # gRPC services (optional)
-│   │   └── account_service.go
-│   └── modules/                      # Feature modules
-│       ├── auth/
-│       │   ├── controllers/
-│       │   │   └── auth_controller.go
-│       │   ├── usecases/
-│       │   │   └── auth_usecase.go
-│       │   ├── dtos/
-│       │   │   └── auth_dto.go
-│       │   └── init.go               # Module init & routes
-│       ├── user/
-│       │   ├── controllers/
-│       │   ├── usecases/
-│       │   ├── dtos/
-│       │   └── init.go
-│       └── {feature}/                # Other modules...
-│           ├── controllers/
-│           ├── usecases/
-│           ├── dtos/
-│           ├── validators/           # (optional) Chain validators
-│           └── init.go
-├── pkg/
+internal/
+├── domain/{domain}/
+│   ├── entities/                    # Aggregates + entities with behavior
+│   │   └── {entity}.go             # New(), state transitions, guard checks
+│   ├── valueobjects/               # Immutable typed values with behavior
+│   │   └── {vo}.go                 # Only stdlib imports
+│   ├── ports/                      # Hexagonal ports — 1 file per interface
+│   │   └── {store_name}.go         # Store interface + related DTOs
+│   ├── events/                     # 1 file per domain event
+│   │   └── {event_name}.go         # Embed shared.BaseEvent
+│   ├── usecases/                   # Business orchestration (pure, no infra)
+│   │   └── {action}.go             # One file per use case
+│   └── validators/                 # (optional) Pure validation rules
+│
+├── domain/shared/
+│   ├── base_event.go               # BaseEvent struct
+│   └── event_collector.go          # EventCollector for entities
+│
+├── application/
+│   ├── ports/http/
+│   │   ├── {module}_handler.go     # Register{Module}Routes + handlers
+│   │   └── {module}_dtos.go        # Request/Response structs
+│   ├── services/
+│   │   └── {module}_service.go     # Thin wrapper → domain usecases
+│   ├── listeners/
+│   │   └── on_{event_name}.go      # Event side-effects
+│   └── eventbus/
+│       ├── dispatcher.go
+│       └── registry.go
+│
+├── infrastructure/
 │   ├── database/
-│   │   ├── database.go               # GORM connection
-│   │   ├── user.go                   # User model
-│   │   └── {entity}.go               # Other models
-│   ├── enums/                        # Enumeration types
-│   ├── events/                       # Event definitions
-│   ├── queue/                        # Task queue (Asynq)
-│   │   ├── tasks.go                  # Task definitions
-│   │   └── client.go                 # Queue client
-│   ├── redis/                        # Redis client
-│   ├── sse/                          # Server-Sent Events
-│   │   └── hub.go                    # SSE Hub
-│   ├── response/                     # HTTP response helpers
-│   ├── logger/                       # Structured logging
-│   ├── storage/                      # File storage (S3/R2)
-│   └── utils/                        # Utility functions
-├── migrations/                       # SQL migrations
-├── chart/                            # Kubernetes Helm charts (optional)
-├── .env.example
-├── go.mod
-├── Makefile
-├── Dockerfile
-└── README.md
+│   │   └── {domain}_{entity}_store.go
+│   ├── cache/
+│   ├── messaging/
+│   ├── auth/
+│   ├── storage/
+│   ├── logger/
+│   └── http/
+│       ├── response.go
+│       └── pagination.go
+│
+├── models/                         # GORM models (persistence only)
+│   └── {entity}.go
+│
+├── middleware/
+│   ├── auth.go
+│   ├── admin_auth.go
+│   ├── cors.go
+│   ├── logger.go
+│   ├── recovery.go
+│   └── api_key.go
+│
+├── config/
+│   └── config.go
+│
+├── bootstrap/
+│   └── app.go                      # App struct with all dependencies
+│
+└── cmd/v1/
+    ├── main.go
+    └── router.go
 ```
 
-## Architecture Pattern
+### Layer Mapping (Generic DDD → Go)
+
+| Generic DDD | Go Path |
+|-------------|---------|
+| `domain/` | `internal/domain/` |
+| `application/ports/{transport}/` | `internal/application/ports/http/` |
+| `application/services/` | `internal/application/services/` |
+| `application/listeners/` | `internal/application/listeners/` |
+| `infrastructure/{persistence}/` | `internal/infrastructure/database/` |
+| `models/` | `internal/models/` |
+
+---
+
+## Layer Rules (Import Rules)
 
 ```
-Controller → Usecase → Database (GORM)
-    ↓           ↓
- Request    Business
- Binding     Logic
-    ↓           ↓
-  DTOs      Models
+domain/valueobjects/   → only stdlib
+domain/entities/        → only stdlib + domain/shared + domain/valueobjects
+domain/ports/           → only stdlib + domain/entities + domain/valueobjects + domain/shared
+domain/events/          → only stdlib + domain/shared
+domain/usecases/        → domain/entities + ports + events + valueobjects (NO infra)
+application/services/   → domain/usecases (thin wrapper)
+application/ports/http/ → application/services + bootstrap + infrastructure/http
+application/listeners/  → domain/events + bootstrap + infrastructure/messaging
+infrastructure/database → domain/ports + models/
 ```
 
-**Layer Responsibilities:**
+---
+
+## Hard Rules
 
-| Layer | Responsibility |
-|-------|----------------|
-| Controller | HTTP handling, request/response, validation |
-| Usecase | Business logic, orchestration |
-| DTO | Data transfer objects, API contracts |
-| Model | Database entities (pkg/database) |
+- `domain/` MUST NOT import gorm, gin, redis, firebase, asynq, or any external package
+- Domain A MUST NOT import Domain B
+- NO circular imports
+- Domain entities returned via API MUST have `json:"snake_case"` tags
+- Async goroutines MUST use `context.Background()`
+- Event names in `NewBaseEvent("...")` MUST match `eventbus/registry.go`
+- Entity SHOULD embed `shared.EventCollector` and raise events on state changes
+- Ports use domain types (entities, value objects), NOT `string` for typed values
+- Store constructors: `NewXxxStore(db *gorm.DB) *XxxStore`
 
-## Module Structure
+---
 
-Each feature is an independent module:
+## Forbidden Imports in Domain
 
 ```
-internal/modules/{feature}/
-├── controllers/
-│   └── {feature}_controller.go   # HTTP handlers
-├── usecases/
-│   └── {feature}_usecase.go      # Business logic
-├── dtos/
-│   └── {feature}_dto.go          # Request/Response DTOs
-├── validators/                    # (optional)
-│   └── {feature}_validator.go    # Chain validators
-└── init.go                        # Module init & route registration
+"gorm.io/*"
+"github.com/gin-gonic/*"
+"github.com/redis/*"
+"firebase.google.com/*"
+"github.com/hibiken/asynq"
 ```
 
-## Key Files
+---
+
+## Domain Layer Examples
+
+### Entity with Behavior
 
-### cmd/api/main.go
 ```go
-package main
+package entities
 
 import (
-    "context"
-    "log"
-    "net/http"
-    "os"
-    "os/signal"
-    "syscall"
     "time"
 
-    "myapp/internal/config"
-    "myapp/pkg/database"
-    "myapp/pkg/redis"
-    "myapp/pkg/queue"
-    "myapp/pkg/sse"
+    "myapp/internal/domain/shared"
+    "myapp/internal/domain/wallet/valueobjects"
 )
 
-func main() {
-    cfg := config.Load()
+type Wallet struct {
+    shared.EventCollector
+    ID        string
+    UserID    string
+    Balance   valueobjects.Money
+    Status    valueobjects.WalletStatus
+    CreatedAt time.Time
+    UpdatedAt time.Time
+}
 
-    // Initialize dependencies
-    db := database.Connect(cfg.Database)
-    redisClient := redis.NewClient(cfg.Redis)
-    queueClient := queue.NewClient(redisClient)
-    sseHub := sse.NewHub(redisClient)
+func NewWallet(userID string) *Wallet {
+    w := &Wallet{
+        ID:        shared.NewID(),
+        UserID:    userID,
+        Balance:   valueobjects.ZeroMoney(),
+        Status:    valueobjects.WalletStatusActive,
+        CreatedAt: time.Now(),
+        UpdatedAt: time.Now(),
+    }
+    w.Raise(events.NewWalletCreated(w.ID, userID))
+    return w
+}
 
-    // Start SSE Hub
-    go sseHub.Run()
+func (w *Wallet) IsActive() bool {
+    return w.Status == valueobjects.WalletStatusActive
+}
 
-    // Setup router
-    router := SetupRouter(db, redisClient, queueClient, sseHub, cfg)
+func (w *Wallet) CanWithdraw(amount valueobjects.Money) bool {
+    return w.IsActive() && w.Balance.GreaterOrEqual(amount)
+}
 
-    // HTTP Server
-    server := &http.Server{
-        Addr:         ":" + cfg.Port,
-        Handler:      router,
-        ReadTimeout:  15 * time.Second,
-        WriteTimeout: 0, // Disabled for SSE
+func (w *Wallet) Withdraw(amount valueobjects.Money) error {
+    if !w.CanWithdraw(amount) {
+        return ErrInsufficientBalance
     }
+    w.Balance = w.Balance.Subtract(amount)
+    w.UpdatedAt = time.Now()
+    w.Raise(events.NewWalletWithdrawalCreated(w.ID, w.UserID, amount))
+    return nil
+}
 
-    // Graceful shutdown
-    go func() {
-        if err := server.ListenAndServe(); err != nil && err != http.ErrServerClosed {
-            log.Fatalf("Server error: %v", err)
-        }
-    }()
+func (w *Wallet) Deposit(amount valueobjects.Money) {
+    w.Balance = w.Balance.Add(amount)
+    w.UpdatedAt = time.Now()
+}
+```
+
+### Value Object
+
+```go
+package valueobjects
+
+import "fmt"
+
+type Money struct {
+    amount   int64
+    currency string
+}
+
+func NewMoney(amount int64, currency string) Money {
+    return Money{amount: amount, currency: currency}
+}
+
+func ZeroMoney() Money {
+    return Money{amount: 0, currency: "VND"}
+}
+
+func (m Money) Amount() int64    { return m.amount }
+func (m Money) Currency() string { return m.currency }
+
+func (m Money) Add(other Money) Money {
+    return Money{amount: m.amount + other.amount, currency: m.currency}
+}
+
+func (m Money) Subtract(other Money) Money {
+    return Money{amount: m.amount - other.amount, currency: m.currency}
+}
+
+func (m Money) GreaterOrEqual(other Money) bool {
+    return m.amount >= other.amount
+}
 
-    quit := make(chan os.Signal, 1)
-    signal.Notify(quit, syscall.SIGINT, syscall.SIGTERM)
-    <-quit
+func (m Money) Format() string {
+    return fmt.Sprintf("%d %s", m.amount, m.currency)
+}
+
+type WalletStatus string
 
-    ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
-    defer cancel()
+const (
+    WalletStatusActive   WalletStatus = "active"
+    WalletStatusFrozen   WalletStatus = "frozen"
+    WalletStatusClosed   WalletStatus = "closed"
+)
 
-    if err := server.Shutdown(ctx); err != nil {
-        log.Fatalf("Shutdown error: %v", err)
+func (s WalletStatus) IsTerminal() bool {
+    return s == WalletStatusClosed
+}
+
+func (s WalletStatus) CanTransitionTo(target WalletStatus) bool {
+    switch s {
+    case WalletStatusActive:
+        return target == WalletStatusFrozen || target == WalletStatusClosed
+    case WalletStatusFrozen:
+        return target == WalletStatusActive || target == WalletStatusClosed
+    default:
+        return false
     }
 }
 ```
 
-### cmd/api/router.go
+### Port Interface
+
 ```go
-package main
+package ports
 
 import (
-    "github.com/gin-gonic/gin"
-    "gorm.io/gorm"
+    "context"
 
-    "myapp/internal/config"
-    "myapp/internal/middleware"
-    "myapp/internal/modules/auth"
-    "myapp/internal/modules/user"
-    "myapp/pkg/queue"
-    "myapp/pkg/redis"
-    "myapp/pkg/sse"
+    "myapp/internal/domain/wallet/entities"
+    "myapp/internal/domain/wallet/valueobjects"
 )
 
-func SetupRouter(
-    db *gorm.DB,
-    redisClient *redis.Client,
-    queueClient *queue.Client,
-    sseHub *sse.Hub,
-    cfg *config.Config,
-) *gin.Engine {
-    r := gin.New()
+type WalletStore interface {
+    FindByID(ctx context.Context, id string) (*entities.Wallet, error)
+    FindByUserID(ctx context.Context, userID string) (*entities.Wallet, error)
+    Save(ctx context.Context, wallet *entities.Wallet) error
+    UpdateBalance(ctx context.Context, id string, balance valueobjects.Money) error
+}
+```
 
-    // Global middleware
-    r.Use(middleware.Recovery())
-    r.Use(middleware.Logger())
-    r.Use(middleware.CORS(cfg.AllowedOrigins))
+### Domain Event
 
-    // Health check
-    r.GET("/health", func(c *gin.Context) {
-        c.JSON(200, gin.H{"status": "ok"})
-    })
+```go
+package events
 
-    // Auth middleware
-    authMiddleware := middleware.NewAuthMiddleware(db, redisClient, cfg.Firebase)
+import "myapp/internal/domain/shared"
 
-    // Initialize modules
-    auth.Init(r, db, redisClient, authMiddleware)
-    user.Init(r, db, authMiddleware)
+type WalletWithdrawalCreated struct {
+    shared.BaseEvent
+    WalletID string
+    UserID   string
+    Amount   int64
+}
 
-    return r
+func NewWalletWithdrawalCreated(walletID, userID string, amount int64) WalletWithdrawalCreated {
+    return WalletWithdrawalCreated{
+        BaseEvent: shared.NewBaseEvent("wallet.withdrawal.created"),
+        WalletID:  walletID,
+        UserID:    userID,
+        Amount:    amount,
+    }
 }
 ```
 
-### internal/modules/auth/init.go
+### Use Case
+
 ```go
-package auth
+package usecases
 
 import (
-    "github.com/gin-gonic/gin"
-    "gorm.io/gorm"
+    "context"
+    "errors"
 
-    "myapp/internal/middleware"
-    "myapp/internal/modules/auth/controllers"
-    "myapp/internal/modules/auth/usecases"
-    "myapp/pkg/redis"
+    "myapp/internal/domain/wallet/entities"
+    "myapp/internal/domain/wallet/ports"
+    "myapp/internal/domain/wallet/valueobjects"
 )
 
-func Init(
-    r *gin.Engine,
-    db *gorm.DB,
-    redisClient *redis.Client,
-    authMiddleware *middleware.AuthMiddleware,
-) {
-    // Initialize usecase
-    usecase := usecases.NewAuthUsecase(db, redisClient)
+type WithdrawUseCase struct {
+    walletStore ports.WalletStore
+}
 
-    // Initialize controller
-    controller := controllers.NewAuthController(usecase)
+func NewWithdrawUseCase(walletStore ports.WalletStore) *WithdrawUseCase {
+    return &WithdrawUseCase{walletStore: walletStore}
+}
 
-    // Register routes
-    authGroup := r.Group("/auth")
-    {
-        authGroup.POST("/verify", controller.VerifyToken)
-
-        // Protected routes
-        protected := authGroup.Group("")
-        protected.Use(authMiddleware.Authenticate())
-        {
-            protected.GET("/me", controller.GetMe)
-            protected.PUT("/me", controller.UpdateMe)
-        }
+func (uc *WithdrawUseCase) Execute(ctx context.Context, walletID string, amount valueobjects.Money) (*entities.Wallet, error) {
+    wallet, err := uc.walletStore.FindByID(ctx, walletID)
+    if err != nil {
+        return nil, err
+    }
+
+    if err := wallet.Withdraw(amount); err != nil {
+        return nil, err
+    }
+
+    if err := uc.walletStore.Save(ctx, wallet); err != nil {
+        return nil, err
     }
+
+    return wallet, nil
 }
 ```
 
-### internal/modules/auth/controllers/auth_controller.go
+---
+
+## Application Layer Examples
+
+### Handler (ports/http)
+
 ```go
-package controllers
+package http
 
 import (
     "net/http"
 
     "github.com/gin-gonic/gin"
 
-    "myapp/internal/modules/auth/dtos"
-    "myapp/internal/modules/auth/usecases"
-    "myapp/pkg/response"
+    "myapp/internal/application/services"
+    "myapp/internal/bootstrap"
+    infrahttp "myapp/internal/infrastructure/http"
 )
 
-type AuthController struct {
-    usecase *usecases.AuthUsecase
+type WalletHandler struct {
+    service *services.WalletService
 }
 
-func NewAuthController(usecase *usecases.AuthUsecase) *AuthController {
-    return &AuthController{usecase: usecase}
+func RegisterWalletRoutes(r *gin.RouterGroup, app *bootstrap.App) {
+    store := database.NewWalletStore(app.DB)
+    withdrawUC := usecases.NewWithdrawUseCase(store)
+    service := services.NewWalletService(withdrawUC)
+    handler := &WalletHandler{service: service}
+
+    wallets := r.Group("/wallets")
+    {
+        wallets.POST("/:id/withdraw", handler.Withdraw)
+        wallets.GET("/:id", handler.GetByID)
+    }
 }
 
-func (c *AuthController) VerifyToken(ctx *gin.Context) {
-    var req dtos.VerifyTokenRequest
-    if err := ctx.ShouldBindJSON(&req); err != nil {
-        response.Error(ctx, http.StatusBadRequest, "Invalid request")
+func (h *WalletHandler) Withdraw(c *gin.Context) {
+    var req WithdrawRequest
+    if err := c.ShouldBindJSON(&req); err != nil {
+        infrahttp.Error(c, http.StatusBadRequest, "Invalid request")
         return
     }
 
-    user, err := c.usecase.VerifyToken(ctx, req.Token)
+    wallet, err := h.service.Withdraw(c, c.Param("id"), req.Amount, req.Currency)
     if err != nil {
-        response.Error(ctx, http.StatusUnauthorized, "Invalid token")
+        infrahttp.Error(c, http.StatusUnprocessableEntity, err.Error())
         return
     }
 
-    response.Success(ctx, dtos.ToUserResponse(user))
+    infrahttp.Success(c, ToWalletResponse(wallet))
 }
+```
 
-func (c *AuthController) GetMe(ctx *gin.Context) {
-    userID := ctx.GetString("user_id")
+### DTOs (ports/http)
 
-    user, err := c.usecase.GetByID(ctx, userID)
-    if err != nil {
-        response.Error(ctx, http.StatusNotFound, "User not found")
-        return
-    }
+```go
+package http
 
-    response.Success(ctx, dtos.ToUserResponse(user))
+import "myapp/internal/domain/wallet/entities"
+
+type WithdrawRequest struct {
+    Amount   int64  `json:"amount" binding:"required,gt=0"`
+    Currency string `json:"currency" binding:"required"`
 }
 
-func (c *AuthController) UpdateMe(ctx *gin.Context) {
-    userID := ctx.GetString("user_id")
+type WalletResponse struct {
+    ID      string `json:"id"`
+    UserID  string `json:"user_id"`
+    Balance int64  `json:"balance"`
+    Status  string `json:"status"`
+}
 
-    var req dtos.UpdateUserRequest
-    if err := ctx.ShouldBindJSON(&req); err != nil {
-        response.Error(ctx, http.StatusBadRequest, "Invalid request")
-        return
+func ToWalletResponse(w *entities.Wallet) *WalletResponse {
+    return &WalletResponse{
+        ID:      w.ID,
+        UserID:  w.UserID,
+        Balance: w.Balance.Amount(),
+        Status:  string(w.Status),
     }
+}
+```
 
-    user, err := c.usecase.Update(ctx, userID, &req)
-    if err != nil {
-        response.Error(ctx, http.StatusInternalServerError, err.Error())
-        return
-    }
+### Service (thin wrapper)
+
+```go
+package services
+
+import (
+    "context"
 
-    response.Success(ctx, dtos.ToUserResponse(user))
+    "myapp/internal/domain/wallet/entities"
+    "myapp/internal/domain/wallet/usecases"
+    "myapp/internal/domain/wallet/valueobjects"
+)
+
+type WalletService struct {
+    withdrawUC *usecases.WithdrawUseCase
+}
+
+func NewWalletService(withdrawUC *usecases.WithdrawUseCase) *WalletService {
+    return &WalletService{withdrawUC: withdrawUC}
+}
+
+func (s *WalletService) Withdraw(ctx context.Context, walletID string, amount int64, currency string) (*entities.Wallet, error) {
+    money := valueobjects.NewMoney(amount, currency)
+    return s.withdrawUC.Execute(ctx, walletID, money)
 }
 ```
 
-### internal/modules/auth/usecases/auth_usecase.go
+### Listener
+
 ```go
-package usecases
+package listeners
+
+import (
+    "context"
+    "log"
+
+    "myapp/internal/bootstrap"
+    "myapp/internal/domain/wallet/events"
+)
+
+func OnWalletWithdrawalCreated(app *bootstrap.App) func(interface{}) {
+    return func(evt interface{}) {
+        event := evt.(events.WalletWithdrawalCreated)
+
+        go func() {
+            ctx := context.Background()
+            log.Printf("Withdrawal created: wallet=%s amount=%d", event.WalletID, event.Amount)
+            // Send notification, update analytics, etc.
+        }()
+    }
+}
+```
+
+---
+
+## Infrastructure Layer Examples
+
+### Store Implementation
+
+```go
+package database
 
 import (
     "context"
-    "errors"
 
     "gorm.io/gorm"
 
-    "myapp/internal/modules/auth/dtos"
-    "myapp/pkg/database"
-    "myapp/pkg/firebase"
-    "myapp/pkg/redis"
+    "myapp/internal/domain/wallet/entities"
+    "myapp/internal/domain/wallet/ports"
+    "myapp/internal/domain/wallet/valueobjects"
+    "myapp/internal/models"
 )
 
-type AuthUsecase struct {
-    db          *gorm.DB
-    redisClient *redis.Client
+var _ ports.WalletStore = (*WalletStore)(nil)
+
+type WalletStore struct {
+    db *gorm.DB
 }
 
-func NewAuthUsecase(db *gorm.DB, redisClient *redis.Client) *AuthUsecase {
-    return &AuthUsecase{
-        db:          db,
-        redisClient: redisClient,
-    }
+func NewWalletStore(db *gorm.DB) *WalletStore {
+    return &WalletStore{db: db}
 }
 
-func (u *AuthUsecase) VerifyToken(ctx context.Context, token string) (*database.User, error) {
-    // Verify Firebase token
-    firebaseToken, err := firebase.VerifyToken(ctx, token)
-    if err != nil {
+func (s *WalletStore) FindByID(ctx context.Context, id string) (*entities.Wallet, error) {
+    var model models.Wallet
+    if err := s.db.WithContext(ctx).First(&model, "id = ?", id).Error; err != nil {
         return nil, err
     }
+    return toEntity(&model), nil
+}
 
-    // Find or create user
-    var user database.User
-    result := u.db.Where("firebase_uid = ?", firebaseToken.UID).First(&user)
+func (s *WalletStore) Save(ctx context.Context, wallet *entities.Wallet) error {
+    model := toModel(wallet)
+    return s.db.WithContext(ctx).Save(model).Error
+}
 
-    if errors.Is(result.Error, gorm.ErrRecordNotFound) {
-        // Create new user
-        user = database.User{
-            FirebaseUID: firebaseToken.UID,
-            Email:       firebaseToken.Claims["email"].(string),
-        }
-        if err := u.db.Create(&user).Error; err != nil {
-            return nil, err
-        }
-    } else if result.Error != nil {
-        return nil, result.Error
+func toEntity(m *models.Wallet) *entities.Wallet {
+    return &entities.Wallet{
+        ID:      m.ID,
+        UserID:  m.UserID,
+        Balance: valueobjects.NewMoney(m.Balance, m.Currency),
+        Status:  valueobjects.WalletStatus(m.Status),
     }
+}
 
-    return &user, nil
+func toModel(e *entities.Wallet) *models.Wallet {
+    return &models.Wallet{
+        ID:       e.ID,
+        UserID:   e.UserID,
+        Balance:  e.Balance.Amount(),
+        Currency: e.Balance.Currency(),
+        Status:   string(e.Status),
+    }
 }
+```
 
-func (u *AuthUsecase) GetByID(ctx context.Context, id string) (*database.User, error) {
-    var user database.User
-    if err := u.db.First(&user, "id = ?", id).Error; err != nil {
-        return nil, err
+### GORM Model
+
+```go
+package models
+
+import (
+    "time"
+
+    "github.com/google/uuid"
+    "gorm.io/gorm"
+)
+
+type Wallet struct {
+    ID        string         `gorm:"type:char(36);primaryKey" json:"id"`
+    UserID    string         `gorm:"type:char(36);index" json:"user_id"`
+    Balance   int64          `gorm:"type:bigint;default:0" json:"balance"`
+    Currency  string         `gorm:"type:varchar(10);default:VND" json:"currency"`
+    Status    string         `gorm:"type:varchar(20);default:active" json:"status"`
+    CreatedAt time.Time      `json:"created_at"`
+    UpdatedAt time.Time      `json:"updated_at"`
+    DeletedAt gorm.DeletedAt `gorm:"index" json:"-"`
+}
+
+func (w *Wallet) BeforeCreate(tx *gorm.DB) error {
+    if w.ID == "" {
+        w.ID = uuid.New().String()
     }
-    return &user, nil
+    return nil
 }
+```
 
-func (u *AuthUsecase) Update(ctx context.Context, id string, req *dtos.UpdateUserRequest) (*database.User, error) {
-    var user database.User
-    if err := u.db.First(&user, "id = ?", id).Error; err != nil {
-        return nil, err
+---
+
+## Wiring Pattern
+
+The `Register{Module}Routes` function wires all layers together:
+
+```
+store → usecase → service → handler → routes
+```
+
+```go
+func Register{Module}Routes(r *gin.RouterGroup, app *bootstrap.App) {
+    // 1. Infrastructure (implements ports)
+    store := database.New{Entity}Store(app.DB)
+
+    // 2. Domain use cases (depends on ports)
+    createUC := usecases.NewCreate{Entity}UseCase(store)
+    listUC := usecases.NewList{Entity}UseCase(store)
+
+    // 3. Application service (thin wrapper)
+    service := services.New{Module}Service(createUC, listUC)
+
+    // 4. HTTP handler
+    handler := &{Module}Handler{service: service}
+
+    // 5. Routes
+    group := r.Group("/{module}")
+    {
+        group.POST("", handler.Create)
+        group.GET("", handler.List)
+        group.GET("/:id", handler.GetByID)
+    }
+}
+```
+
+### Bootstrap App Struct
+
+```go
+package bootstrap
+
+import (
+    "gorm.io/gorm"
+
+    "myapp/internal/application/eventbus"
+    "myapp/internal/config"
+)
+
+type App struct {
+    DB         *gorm.DB
+    Config     *config.Config
+    EventBus   *eventbus.Dispatcher
+    // Add other shared dependencies
+}
+```
+
+### Router Setup
+
+```go
+func SetupRouter(app *bootstrap.App) *gin.Engine {
+    r := gin.New()
+
+    r.Use(middleware.Recovery())
+    r.Use(middleware.Logger())
+    r.Use(middleware.CORS(app.Config.AllowedOrigins))
+
+    r.GET("/health", func(c *gin.Context) {
+        c.JSON(200, gin.H{"status": "ok"})
+    })
+
+    v1 := r.Group("/v1")
+    {
+        http.RegisterWalletRoutes(v1, app)
+        http.RegisterAuthRoutes(v1, app)
+        // Register more domains here
     }
 
-    updates := map[string]interface{}{}
-    if req.Name != nil {
-        updates["name"] = *req.Name
+    return r
+}
+```
+
+---
+
+## Check Scripts
+
+```bash
+DOMAIN={domain}
+
+echo "=== Build ==="
+go build ./internal/domain/$DOMAIN/... && echo "PASS" || echo "FAIL"
+
+echo "=== Vet ==="
+go vet ./internal/domain/$DOMAIN/... && echo "PASS" || echo "FAIL"
+
+echo "=== Domain Purity ==="
+grep -rn '"gorm.io\|"github.com/gin\|"github.com/redis\|"firebase.google.com\|"github.com/hibiken' internal/domain/$DOMAIN/ && echo "FAIL: infra in domain" || echo "PASS"
+
+echo "=== No Cross-Domain Imports ==="
+for d in $(ls internal/domain/ | grep -v shared | grep -v $DOMAIN); do
+    grep -rn "domain/$d" internal/domain/$DOMAIN/ && echo "FAIL: imports domain/$d"
+done
+
+echo "=== Tests ==="
+go test ./internal/domain/$DOMAIN/... -v && echo "PASS" || echo "FAIL"
+```
+
+---
+
+## Test Patterns
+
+### Entity Tests (pure, no mocks)
+
+```go
+package entities_test
+
+import (
+    "testing"
+
+    "myapp/internal/domain/wallet/entities"
+    "myapp/internal/domain/wallet/valueobjects"
+)
+
+func TestWallet_Withdraw_Success(t *testing.T) {
+    wallet := entities.NewWallet("user-1")
+    wallet.Deposit(valueobjects.NewMoney(10000, "VND"))
+
+    err := wallet.Withdraw(valueobjects.NewMoney(5000, "VND"))
+
+    if err != nil {
+        t.Fatalf("expected no error, got %v", err)
     }
-    if req.Phone != nil {
-        updates["phone"] = *req.Phone
+    if wallet.Balance.Amount() != 5000 {
+        t.Fatalf("expected balance 5000, got %d", wallet.Balance.Amount())
     }
+}
 
-    if err := u.db.Model(&user).Updates(updates).Error; err != nil {
-        return nil, err
+func TestWallet_Withdraw_InsufficientBalance(t *testing.T) {
+    wallet := entities.NewWallet("user-1")
+    wallet.Deposit(valueobjects.NewMoney(1000, "VND"))
+
+    err := wallet.Withdraw(valueobjects.NewMoney(5000, "VND"))
+
+    if err == nil {
+        t.Fatal("expected error for insufficient balance")
     }
+}
+
+func TestWallet_RaisesEventOnWithdraw(t *testing.T) {
+    wallet := entities.NewWallet("user-1")
+    wallet.Deposit(valueobjects.NewMoney(10000, "VND"))
+    wallet.ClearEvents()
+
+    wallet.Withdraw(valueobjects.NewMoney(5000, "VND"))
 
-    return &user, nil
+    events := wallet.Events()
+    if len(events) != 1 {
+        t.Fatalf("expected 1 event, got %d", len(events))
+    }
 }
 ```
 
-### internal/modules/auth/dtos/auth_dto.go
+### UseCase Tests (mock ports)
+
 ```go
-package dtos
+package usecases_test
+
+import (
+    "context"
+    "testing"
+
+    "myapp/internal/domain/wallet/entities"
+    "myapp/internal/domain/wallet/usecases"
+    "myapp/internal/domain/wallet/valueobjects"
+)
 
-import "myapp/pkg/database"
+type mockWalletStore struct {
+    wallet *entities.Wallet
+    saved  *entities.Wallet
+}
 
-type VerifyTokenRequest struct {
-    Token string `json:"token" binding:"required"`
+func (m *mockWalletStore) FindByID(ctx context.Context, id string) (*entities.Wallet, error) {
+    if m.wallet != nil && m.wallet.ID == id {
+        return m.wallet, nil
+    }
+    return nil, errors.New("not found")
 }
 
-type UpdateUserRequest struct {
-    Name  *string `json:"name"`
-    Phone *string `json:"phone"`
+func (m *mockWalletStore) Save(ctx context.Context, wallet *entities.Wallet) error {
+    m.saved = wallet
+    return nil
 }
 
-type UserResponse struct {
-    ID        string  `json:"id"`
-    Email     string  `json:"email"`
-    Name      *string `json:"name"`
-    Phone     *string `json:"phone"`
-    AvatarURL *string `json:"avatar_url"`
-    CreatedAt string  `json:"created_at"`
+func TestWithdrawUseCase_Success(t *testing.T) {
+    wallet := entities.NewWallet("user-1")
+    wallet.Deposit(valueobjects.NewMoney(10000, "VND"))
+
+    store := &mockWalletStore{wallet: wallet}
+    uc := usecases.NewWithdrawUseCase(store)
+
+    result, err := uc.Execute(context.Background(), wallet.ID, valueobjects.NewMoney(5000, "VND"))
+
+    if err != nil {
+        t.Fatalf("expected no error, got %v", err)
+    }
+    if result.Balance.Amount() != 5000 {
+        t.Fatalf("expected 5000, got %d", result.Balance.Amount())
+    }
+    if store.saved == nil {
+        t.Fatal("expected wallet to be saved")
+    }
 }
+```
+
+### Integration Tests (real DB)
 
-func ToUserResponse(user *database.User) *UserResponse {
-    return &UserResponse{
-        ID:        user.ID,
-        Email:     user.Email,
-        Name:      user.Name,
-        Phone:     user.Phone,
-        AvatarURL: user.AvatarURL,
-        CreatedAt: user.CreatedAt.Format("2006-01-02T15:04:05Z"),
+```go
+package database_test
+
+import (
+    "context"
+    "testing"
+
+    "myapp/internal/infrastructure/database"
+    "myapp/internal/domain/wallet/entities"
+    "myapp/internal/domain/wallet/valueobjects"
+    "myapp/internal/models"
+    "myapp/internal/testutil"
+)
+
+func TestWalletStore_SaveAndFind(t *testing.T) {
+    db := testutil.SetupTestDB(t)
+    db.AutoMigrate(&models.Wallet{})
+
+    store := database.NewWalletStore(db)
+    ctx := context.Background()
+
+    wallet := entities.NewWallet("user-1")
+    wallet.Deposit(valueobjects.NewMoney(10000, "VND"))
+
+    err := store.Save(ctx, wallet)
+    if err != nil {
+        t.Fatalf("save failed: %v", err)
+    }
+
+    found, err := store.FindByID(ctx, wallet.ID)
+    if err != nil {
+        t.Fatalf("find failed: %v", err)
+    }
+
+    if found.Balance.Amount() != 10000 {
+        t.Fatalf("expected 10000, got %d", found.Balance.Amount())
     }
 }
 ```
 
-### internal/middleware/auth.go
+---
+
+## Naming Conventions
+
+| Item | Convention | Example |
+|------|------------|---------|
+| Package | lowercase, short | `entities`, `usecases`, `ports` |
+| Domain folder | snake_case | `bank_account/` |
+| File | snake_case | `wallet_store.go`, `withdraw.go` |
+| Entity struct | PascalCase | `Wallet`, `Transaction` |
+| Value object struct | PascalCase | `Money`, `WalletStatus` |
+| Port interface | PascalCase + Store/Client suffix | `WalletStore`, `PaymentClient` |
+| UseCase struct | PascalCase + UseCase suffix | `WithdrawUseCase` |
+| Handler struct | PascalCase + Handler suffix | `WalletHandler` |
+| Service struct | PascalCase + Service suffix | `WalletService` |
+| Constructor | `New` prefix | `NewWallet()`, `NewWalletStore()` |
+| Private func | camelCase | `validateToken`, `toEntity` |
+| Constants | PascalCase | `WalletStatusActive` |
+| Event struct | `{Domain}{Action}` PascalCase | `WalletWithdrawalCreated` |
+| Listener file | `on_{event_name}.go` | `on_wallet_withdrawal_created.go` |
+| Handler file | `{module}_handler.go` | `wallet_handler.go` |
+| DTO file | `{module}_dtos.go` | `wallet_dtos.go` |
+| Store file | `{domain}_{entity}_store.go` | `wallet_wallet_store.go` |
+
+---
+
+## Middleware
+
 ```go
 package middleware
 
@@ -470,21 +873,18 @@ import (
     "github.com/gin-gonic/gin"
     "gorm.io/gorm"
 
-    "myapp/pkg/database"
-    "myapp/pkg/firebase"
-    "myapp/pkg/redis"
+    "myapp/internal/models"
+    "myapp/internal/infrastructure/auth"
+    "myapp/internal/infrastructure/cache"
 )
 
 type AuthMiddleware struct {
     db          *gorm.DB
-    redisClient *redis.Client
+    cache       cache.Client
 }
 
-func NewAuthMiddleware(db *gorm.DB, redisClient *redis.Client) *AuthMiddleware {
-    return &AuthMiddleware{
-        db:          db,
-        redisClient: redisClient,
-    }
+func NewAuthMiddleware(db *gorm.DB, cache cache.Client) *AuthMiddleware {
+    return &AuthMiddleware{db: db, cache: cache}
 }
 
 func (m *AuthMiddleware) Authenticate() gin.HandlerFunc {
@@ -497,30 +897,26 @@ func (m *AuthMiddleware) Authenticate() gin.HandlerFunc {
 
         token := strings.TrimPrefix(authHeader, "Bearer ")
 
-        // Check Redis cache first
         cacheKey := "auth:" + token[:32]
-        if cached, err := m.redisClient.Get(c, cacheKey); err == nil {
+        if cached, err := m.cache.Get(c, cacheKey); err == nil {
             c.Set("user_id", cached)
             c.Next()
             return
         }
 
-        // Verify Firebase token
-        firebaseToken, err := firebase.VerifyToken(c, token)
+        firebaseToken, err := auth.VerifyToken(c, token)
         if err != nil {
             c.AbortWithStatusJSON(http.StatusUnauthorized, gin.H{"error": "Invalid token"})
             return
         }
 
-        // Get user from database
-        var user database.User
+        var user models.User
         if err := m.db.Where("firebase_uid = ?", firebaseToken.UID).First(&user).Error; err != nil {
             c.AbortWithStatusJSON(http.StatusUnauthorized, gin.H{"error": "User not found"})
             return
         }
 
-        // Cache for 1 hour
-        m.redisClient.Set(c, cacheKey, user.ID, time.Hour)
+        m.cache.Set(c, cacheKey, user.ID, time.Hour)
 
         c.Set("user_id", user.ID)
         c.Set("user", &user)
@@ -538,13 +934,13 @@ func (m *AuthMiddleware) Optional() gin.HandlerFunc {
 
         token := strings.TrimPrefix(authHeader, "Bearer ")
 
-        firebaseToken, err := firebase.VerifyToken(c, token)
+        firebaseToken, err := auth.VerifyToken(c, token)
         if err != nil {
             c.Next()
             return
         }
 
-        var user database.User
+        var user models.User
         if err := m.db.Where("firebase_uid = ?", firebaseToken.UID).First(&user).Error; err == nil {
             c.Set("user_id", user.ID)
             c.Set("user", &user)
@@ -555,87 +951,12 @@ func (m *AuthMiddleware) Optional() gin.HandlerFunc {
 }
 ```
 
-### pkg/database/database.go
-```go
-package database
+---
 
-import (
-    "fmt"
-    "log"
+## HTTP Response Helpers
 
-    "gorm.io/driver/mysql"
-    "gorm.io/gorm"
-    "gorm.io/gorm/logger"
-)
-
-type Config struct {
-    Host     string
-    Port     string
-    User     string
-    Password string
-    Name     string
-}
-
-func Connect(cfg Config) *gorm.DB {
-    dsn := fmt.Sprintf("%s:%s@tcp(%s:%s)/%s?charset=utf8mb4&parseTime=True&loc=UTC",
-        cfg.User, cfg.Password, cfg.Host, cfg.Port, cfg.Name)
-
-    db, err := gorm.Open(mysql.Open(dsn), &gorm.Config{
-        Logger: logger.Default.LogMode(logger.Info),
-    })
-    if err != nil {
-        log.Fatalf("Failed to connect to database: %v", err)
-    }
-
-    sqlDB, _ := db.DB()
-    sqlDB.SetMaxOpenConns(100)
-    sqlDB.SetMaxIdleConns(10)
-
-    // Auto-migrate models
-    db.AutoMigrate(
-        &User{},
-        // Add other models here
-    )
-
-    return db
-}
-```
-
-### pkg/database/user.go
 ```go
-package database
-
-import (
-    "time"
-
-    "github.com/google/uuid"
-    "gorm.io/gorm"
-)
-
-type User struct {
-    ID          string         `gorm:"type:char(36);primaryKey" json:"id"`
-    FirebaseUID string         `gorm:"type:varchar(128);uniqueIndex" json:"-"`
-    Email       string         `gorm:"type:varchar(255);uniqueIndex" json:"email"`
-    Name        *string        `gorm:"type:varchar(255)" json:"name"`
-    Phone       *string        `gorm:"type:varchar(20)" json:"phone"`
-    AvatarURL   *string        `gorm:"type:varchar(500)" json:"avatar_url"`
-    Status      string         `gorm:"type:varchar(20);default:active" json:"status"`
-    CreatedAt   time.Time      `json:"created_at"`
-    UpdatedAt   time.Time      `json:"updated_at"`
-    DeletedAt   gorm.DeletedAt `gorm:"index" json:"-"`
-}
-
-func (u *User) BeforeCreate(tx *gorm.DB) error {
-    if u.ID == "" {
-        u.ID = uuid.New().String()
-    }
-    return nil
-}
-```
-
-### pkg/response/response.go
-```go
-package response
+package http
 
 import "github.com/gin-gonic/gin"
 
@@ -654,42 +975,31 @@ type Meta struct {
 }
 
 func Success(c *gin.Context, data interface{}) {
-    c.JSON(200, Response{
-        Success: true,
-        Data:    data,
-    })
+    c.JSON(200, Response{Success: true, Data: data})
 }
 
 func SuccessWithMeta(c *gin.Context, data interface{}, meta *Meta) {
-    c.JSON(200, Response{
-        Success: true,
-        Data:    data,
-        Meta:    meta,
-    })
+    c.JSON(200, Response{Success: true, Data: data, Meta: meta})
 }
 
 func Error(c *gin.Context, status int, message string) {
-    c.JSON(status, Response{
-        Success: false,
-        Error:   message,
-    })
+    c.JSON(status, Response{Success: false, Error: message})
 }
 
 func Created(c *gin.Context, data interface{}) {
-    c.JSON(201, Response{
-        Success: true,
-        Data:    data,
-    })
+    c.JSON(201, Response{Success: true, Data: data})
 }
 ```
 
-### pkg/queue/tasks.go (Asynq)
+---
+
+## Background Workers (Asynq)
+
 ```go
 package queue
 
 import (
     "encoding/json"
-
     "github.com/hibiken/asynq"
 )
 
@@ -700,10 +1010,10 @@ const (
 )
 
 type NotificationPayload struct {
-    UserID  string `json:"user_id"`
-    Title   string `json:"title"`
-    Body    string `json:"body"`
-    Data    map[string]string `json:"data"`
+    UserID string            `json:"user_id"`
+    Title  string            `json:"title"`
+    Body   string            `json:"body"`
+    Data   map[string]string `json:"data"`
 }
 
 func NewSendNotificationTask(payload *NotificationPayload) (*asynq.Task, error) {
@@ -715,206 +1025,11 @@ func NewSendNotificationTask(payload *NotificationPayload) (*asynq.Task, error)
 }
 ```
 
-### pkg/sse/hub.go (Server-Sent Events)
-```go
-package sse
-
-import (
-    "context"
-    "encoding/json"
-    "sync"
-
-    "myapp/pkg/redis"
-)
-
-type Client struct {
-    UserID  string
-    Channel chan []byte
-}
-
-type Hub struct {
-    clients     map[string]map[*Client]bool
-    register    chan *Client
-    unregister  chan *Client
-    broadcast   chan *Message
-    mutex       sync.RWMutex
-    redisClient *redis.Client
-}
-
-type Message struct {
-    UserID string      `json:"user_id,omitempty"`
-    Type   string      `json:"type"`
-    Data   interface{} `json:"data"`
-}
-
-func NewHub(redisClient *redis.Client) *Hub {
-    return &Hub{
-        clients:     make(map[string]map[*Client]bool),
-        register:    make(chan *Client),
-        unregister:  make(chan *Client),
-        broadcast:   make(chan *Message, 256),
-        redisClient: redisClient,
-    }
-}
-
-func (h *Hub) Run() {
-    // Subscribe to Redis for cross-instance communication
-    go h.subscribeRedis()
-
-    for {
-        select {
-        case client := <-h.register:
-            h.mutex.Lock()
-            if h.clients[client.UserID] == nil {
-                h.clients[client.UserID] = make(map[*Client]bool)
-            }
-            h.clients[client.UserID][client] = true
-            h.mutex.Unlock()
-
-        case client := <-h.unregister:
-            h.mutex.Lock()
-            if clients, ok := h.clients[client.UserID]; ok {
-                delete(clients, client)
-                close(client.Channel)
-                if len(clients) == 0 {
-                    delete(h.clients, client.UserID)
-                }
-            }
-            h.mutex.Unlock()
-
-        case message := <-h.broadcast:
-            h.broadcastLocal(message)
-        }
-    }
-}
-
-func (h *Hub) BroadcastUser(userID string, msgType string, data interface{}) {
-    msg := &Message{
-        UserID: userID,
-        Type:   msgType,
-        Data:   data,
-    }
-
-    // Publish to Redis for cross-instance
-    payload, _ := json.Marshal(msg)
-    h.redisClient.Publish(context.Background(), "sse:broadcast", payload)
-}
-
-func (h *Hub) broadcastLocal(msg *Message) {
-    h.mutex.RLock()
-    defer h.mutex.RUnlock()
-
-    payload, _ := json.Marshal(msg)
-
-    if msg.UserID != "" {
-        if clients, ok := h.clients[msg.UserID]; ok {
-            for client := range clients {
-                select {
-                case client.Channel <- payload:
-                default:
-                    close(client.Channel)
-                    delete(clients, client)
-                }
-            }
-        }
-    }
-}
-
-func (h *Hub) subscribeRedis() {
-    pubsub := h.redisClient.Subscribe(context.Background(), "sse:broadcast")
-    ch := pubsub.Channel()
-
-    for msg := range ch {
-        var message Message
-        if err := json.Unmarshal([]byte(msg.Payload), &message); err == nil {
-            h.broadcast <- &message
-        }
-    }
-}
-
-func (h *Hub) Register(client *Client) {
-    h.register <- client
-}
-
-func (h *Hub) Unregister(client *Client) {
-    h.unregister <- client
-}
-```
-
-### cmd/background/main.go (Cobra CLI)
-```go
-package main
-
-import (
-    "log"
-
-    "github.com/spf13/cobra"
-
-    "myapp/cmd/background/commands"
-)
-
-func main() {
-    rootCmd := &cobra.Command{
-        Use:   "worker",
-        Short: "Background worker CLI",
-    }
-
-    rootCmd.AddCommand(commands.ConsumerCmd())
-    rootCmd.AddCommand(commands.SchedulerCmd())
-    rootCmd.AddCommand(commands.SyncCmd())
-
-    if err := rootCmd.Execute(); err != nil {
-        log.Fatal(err)
-    }
-}
-```
-
-### cmd/background/commands/consumer.go
-```go
-package commands
-
-import (
-    "log"
-
-    "github.com/hibiken/asynq"
-    "github.com/spf13/cobra"
-
-    "myapp/cmd/background/consumers"
-    "myapp/internal/config"
-    "myapp/pkg/database"
-    "myapp/pkg/queue"
-)
-
-func ConsumerCmd() *cobra.Command {
-    return &cobra.Command{
-        Use:   "consumer",
-        Short: "Start task consumer",
-        Run: func(cmd *cobra.Command, args []string) {
-            cfg := config.Load()
-            db := database.Connect(cfg.Database)
-
-            srv := asynq.NewServer(
-                asynq.RedisClientOpt{Addr: cfg.Redis.Addr},
-                asynq.Config{
-                    Concurrency: 10,
-                },
-            )
-
-            mux := asynq.NewServeMux()
-            mux.HandleFunc(queue.TaskSendNotification, consumers.HandleSendNotification(db))
-            mux.HandleFunc(queue.TaskCleanup, consumers.HandleCleanup(db))
-
-            if err := srv.Run(mux); err != nil {
-                log.Fatalf("Failed to run server: %v", err)
-            }
-        },
-    }
-}
-```
+---
 
 ## Validator Chain Pattern (Optional)
 
-For complex validations:
+For complex domain validations that compose multiple rules:
 
 ```go
 package validators
@@ -933,9 +1048,7 @@ type ValidatorChain struct {
 }
 
 func NewValidatorChain() *ValidatorChain {
-    return &ValidatorChain{
-        validators: make([]Validator, 0),
-    }
+    return &ValidatorChain{validators: make([]Validator, 0)}
 }
 
 func (c *ValidatorChain) Add(v Validator) *ValidatorChain {
@@ -951,89 +1064,53 @@ func (c *ValidatorChain) Validate(ctx context.Context, data interface{}) error {
     }
     return nil
 }
-
-// Example validator
-type AmountValidator struct {
-    MinAmount int64
-    MaxAmount int64
-}
-
-func (v *AmountValidator) Validate(ctx context.Context, data interface{}) error {
-    amount := data.(int64)
-    if amount < v.MinAmount {
-        return errors.New("amount too small")
-    }
-    if amount > v.MaxAmount {
-        return errors.New("amount too large")
-    }
-    return nil
-}
 ```
 
-## Conventions
-
-| Item | Convention | Example |
-|------|------------|---------|
-| Package | lowercase, short | `auth`, `user` |
-| Module folder | snake_case | `bank_account/` |
-| File | snake_case | `auth_controller.go` |
-| Struct | PascalCase | `AuthController` |
-| Interface | PascalCase | `Validator` |
-| Function | PascalCase | `GetByID`, `Create` |
-| Private func | camelCase | `validateToken` |
-| Constants | PascalCase | `TaskSendNotification` |
-| Enums | PascalCase | `StatusActive` |
+---
 
 ## Makefile
 
 ```makefile
-.PHONY: dev run build test migrate
+.PHONY: dev run build test migrate lint domain-check
 
 dev:
 	air
 
 run:
-	go run cmd/api/main.go
+	go run internal/cmd/v1/main.go
 
 build:
-	go build -o bin/api cmd/api/main.go
-	go build -o bin/worker cmd/background/main.go
+	go build -o bin/api internal/cmd/v1/main.go
 
 test:
 	go test -v ./...
 
+test-domain:
+	go test -v ./internal/domain/...
+
 migrate:
 	go run cmd/migrate/main.go
 
-worker-consumer:
-	go run cmd/background/main.go consumer
+lint:
+	go vet ./...
 
-worker-scheduler:
-	go run cmd/background/main.go scheduler
+domain-check:
+	@echo "=== Domain Purity ===" && \
+	grep -rn '"gorm.io\|"github.com/gin\|"github.com/redis\|"firebase.google.com\|"github.com/hibiken' internal/domain/ && echo "FAIL: infra in domain" || echo "PASS"
 ```
 
-## Tech Stack
-
-| Component | Technology |
-|-----------|------------|
-| Framework | Gin |
-| ORM | GORM |
-| Database | MySQL/PostgreSQL |
-| Cache | Redis |
-| Queue | Asynq |
-| Auth | Firebase Auth |
-| CLI | Cobra |
-| gRPC | google.golang.org/grpc |
-| Storage | AWS S3 / Cloudflare R2 |
+---
 
 ## When to Use What
 
 | Scenario | Solution |
 |----------|----------|
-| Simple CRUD | Controller → Usecase → Model |
-| Complex validation | Validator Chain pattern |
-| Background jobs | Asynq task queue |
-| Real-time events | SSE Hub + Redis pub/sub |
-| Inter-service | gRPC |
-| File upload | Storage package (S3/R2) |
-| Push notifications | FCM via queue |
+| New business capability | New domain with entities, ports, usecases |
+| Simple CRUD | Domain entity + store port + single usecase |
+| Complex validation | Validator Chain in domain/validators |
+| Background jobs | Asynq task queue (infrastructure) |
+| Real-time events | SSE Hub + Redis pub/sub (infrastructure) |
+| Cross-domain communication | Domain events via EventBus |
+| Inter-service | gRPC (infrastructure) |
+| File upload | Storage adapter (infrastructure) |
+| Push notifications | FCM via Asynq queue |