Request Flow Traces Chapter 08

Step 1: Client sends request

The client sends a POST to the gateway with email and password.

POST https://acme.app.com:8080/api/v1/auth/login
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "secret123"
}

Step 2: Gateway middleware chain

apps/gateway-service/cmd/server/main.go:130-134

The request enters the gateway and passes through the middleware chain. Middleware is applied in reverse order (last .Use() is outermost).

// Applied bottom-to-top: tracing wraps everything, tenant is next, etc.
var handlerChain http.Handler = mux
handlerChain = middleware.CORSMiddleware(handlerChain)             // 4. Sets CORS headers
handlerChain = middleware.RequestIDMiddleware(handlerChain)        // 3. Generates UUID, sets X-Request-ID
handlerChain = middleware.TenantIdentifierMiddleware(baseDomain)(handlerChain)  // 2. Extracts "acme" from Host, sets X-Subdomain
handlerChain = tracing.Middleware(handlerChain)                   // 1. Creates OTel span

After this chain, request headers now include: X-Request-ID: <uuid>, X-Subdomain: acme, plus an active OpenTelemetry span.

Step 3: Gateway route matching & proxy

apps/gateway-service/internal/handler/router.go:29-49

The Router's ServeHTTP method matches the request path against routes.yaml using prefix matching.

func (rtr *Router) ServeHTTP(w http.ResponseWriter, r *http.Request) {
    route := rtr.findRoute(r.URL.Path)
    // Path "/api/v1/auth/login" matches route: path="/api/v1/auth"
    // Config: auth_required=false, target_url="http://localhost:8081"

    if route.AuthRequired {
        // SKIPPED for /api/v1/auth — auth-service handles its own auth
    }

    rtr.proxyRequest(w, r, route)  // → reverse proxy to http://localhost:8081
}

Step 4: Auth-service receives proxied request

apps/auth-service/cmd/server/main.go:133-138

The auth-service's Chi router matches the /login endpoint. This route sits outside the authenticated group, so no JWT middleware is applied.

r.Route("/api/v1/auth", func(r chi.Router) {
    r.Post("/login", authHandler.Login)          // ← matched! No auth required
    r.Post("/refresh-token", authHandler.RefreshToken)
    // ...
    r.Group(func(ar chi.Router) {
        ar.Use(auth.JWTMiddleware(cfg.JwtCfg))       // JWT required for this group
        ar.Use(auth.TenantContextFromClaimsMiddleware)
        ar.Route("/users", func(r chi.Router) { ... })
    })
})

Step 5: Handler decodes & validates

apps/auth-service/internal/handler/auth.go:20-46

The Login handler decodes JSON, validates fields, calls the service layer, and sets response cookies.

func (h *authHandler) Login(w http.ResponseWriter, r *http.Request) {
    var req model.AuthLogin
    if err := httpx.DecodeAndValidate(r, &req); err != nil {
        httpx.ValidationError(w, err)  // 400 with field-level errors
        return
    }

    resp, err := h.svc.Login(&req, r.Context())  // → Step 6
    if err != nil {
        httpx.HandleError(w, err)  // maps to HTTP status via typed errors
        return
    }

    httpx.SetRefreshTokenCookie(resp.RefreshToken, w)  // HttpOnly cookie
    httpx.SetTenantIdCookie(resp.TenantId, w)

    data := map[string]interface{}{
        "user_id":   resp.UserId,
        "token":     resp.Token,
        "tenant_id": tenantID,
        "subdomain": resp.Subdomain,
    }
    json.NewEncoder(w).Encode(data)
}

Step 6: Service — business logic

apps/auth-service/internal/service/auth_service.go:33-71

The service layer orchestrates the full login sequence: DB lookup, password verification, cross-service tenant fetch, and JWT generation.

func (s *authService) Login(p *model.AuthLogin, ctx context.Context) (*domain.LoginResponse, error) {
    user, err := s.repo.Login(p)                       // → Step 7: DB query
    if err != nil { return nil, err }

    err = bcrypt.CompareHashAndPassword(                // Verify password
        []byte(user.Password), []byte(p.Password))
    if err != nil {
        return nil, httpx.Unauthorized("invalid credentials")
    }

    if user.IsActive != nil && !*user.IsActive {
        return nil, httpx.Unauthorized("account is deactivated")
    }

    tenantData, err := s.GetTenantData(tenantId)       // → Step 8: HTTP → admin-service
    tokenStr, refreshToken, err := s.repo.GetAccessToken(user, ctx, tenantData)  // → Step 9

    return &domain.LoginResponse{
        UserId: user.ID.String(), Token: tokenStr,
        RefreshToken: refreshToken, TenantId: tenantId,
        Subdomain: tenantData["Subdomain"],
    }, nil
}

Step 7: Repository — database query

apps/auth-service/internal/repository/auth_repo.go:35-47

GORM query with eager loading. Preloads the entire role/permission tree in a single operation.

func (r *authRepository) Login(p *model.AuthLogin) (*model.User, error) {
    var u model.User
    if err := r.db.
        Preload("Role.RoleMenu.Menu").        // Eager load: User → Role → []RoleMenu → Menu
        Where("email = ? or phone = ?", p.Email, p.Email).
        First(&u).Error; err != nil {
        if errors.Is(err, gorm.ErrRecordNotFound) {
            return nil, httpx.Unauthorized("invalid credentials")
        }
        return nil, err
    }
    return &u, nil
}
// SQL generated (approx):
// SELECT * FROM users WHERE email = $1 OR phone = $1 LIMIT 1
// SELECT * FROM roles WHERE id = $1
// SELECT * FROM role_menus WHERE role_id = $1
// SELECT * FROM menus WHERE id IN ($1, $2, ...)

Step 8: Cross-service call to admin-service

apps/auth-service/internal/service/auth_service.go:99-115

The auth-service calls admin-service over HTTP to fetch tenant metadata (subdomain, features). This is a synchronous service-to-service call.

func (s *authService) GetTenantData(tenantID string) (map[string]any, error) {
    url := s.internalUrl.AdminServiceUrl + "/me/tenants/" + tenantID
    // e.g. "http://localhost:8082/internal/me/tenants/abc-123"
    respAuth, err := httpx.DoJSON("GET", url, nil, "")

    var result map[string]any
    json.NewDecoder(respAuth.Body).Decode(&result)
    return result, nil  // { "Subdomain": "acme", "Features": [...], ... }
}

Step 9: JWT generation + Redis sync

apps/auth-service/internal/repository/auth_repo.go:170-278

Generates the access token (JWT with claims), creates a refresh token (UUID hashed with SHA-256), and syncs version numbers to Redis for real-time invalidation.

func (r *authRepository) GenerateAccessToken(user, ctx, tenantData) (string, error) {
    // Build permission map from user's role menus
    permissions := map[string][]string{
        "broadcast": {"read", "create"},
        "users":     {"read", "create", "update", "delete"},
        // ... built from Role.RoleMenu.Menu + Can* flags
    }

    claims := jwt.MapClaims{
        "sub":               user.ID,
        "tenant_id":         user.TenantId,
        "role":              roleName,
        "subdomain":         tenantData["Subdomain"],
        "permissions":       permissions,
        "role_id":           user.RoleId,
        "token_version":     tokenVersion,
        "role_version":      roleVersion,
        "role_user_version": roleUserVersion,
        "tenant_feature":    tenantFeature,
        "exp":               time.Now().Add(r.accessTokenExpiry).Unix(),
    }
    token := jwt.NewWithClaims(jwt.SigningMethodHS256, claims)
    tokenStr, _ := token.SignedString([]byte(r.secret))

    // Sync versions to Redis for real-time invalidation
    redisclient.SyncAuthVersion(ctx, "auth:token_version:", userId, tokenVersion)
    redisclient.SyncAuthVersion(ctx, "auth:role_version:", roleId, roleVersion)
    redisclient.SyncAuthVersion(ctx, "auth:role_user_version:", userId, roleUserVersion)

    return tokenStr, nil
}

// Refresh token: UUID → SHA-256 hash → stored in DB
func (r *authRepository) AccessAndRefreshToken(...) {
    newRefresh := uuid.NewString()
    newHash := helpers.HashRefreshToken(newRefresh)
    newRT := model.RefreshToken{ID: uuid.New(), UserID: user.ID, TokenHash: newHash, ...}
    db.Create(&newRT)
}

Step 10: Response

The response flows back through the reverse proxy to the client.

// HTTP Response: 200 OK
// Set-Cookie: refresh_token=<uuid>; HttpOnly; Path=/
// Set-Cookie: tenant_id=<uuid>; Path=/
{
  "user_id": "550e8400-e29b-41d4-a716-446655440000",
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "tenant_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "subdomain": "acme"
}

Step 1: Meta sends POST to webhook endpoint

Meta's WhatsApp Business API sends a webhook notification to our endpoint.

POST /api/v1/webhooks/meta
X-Hub-Signature-256: sha256=abc123def456...
Content-Type: application/json

{
  "object": "whatsapp_business_account",
  "entry": [{
    "id": "waba_123456789",
    "changes": [{
      "field": "messages",
      "value": {
        "statuses": [{ "id": "wamid.xxx", "status": "delivered", ... }]
      }
    }]
  }]
}

Step 2: meta-webhook-service handler

apps/meta-webhook-service/internal/handler/webhook_handler.go:86-138

The handler reads the raw body (required for HMAC verification), validates the signature, and parses the payload.

func (h *WebhookHandler) HandleWebhookEvent(w, r) {
    // 1. Read raw body for signature validation
    body, _ := io.ReadAll(r.Body)

    // 2. Validate HMAC-SHA256 signature with Meta app secret
    signature := r.Header.Get("X-Hub-Signature-256")
    if err := h.validator.Validate(signature, body); err != nil {
        http.Error(w, "Invalid signature", 401)
        return
    }

    // 3. Parse JSON payload
    var payload sharedModel.MetaWebhookPayload
    json.Unmarshal(body, &payload)

    // 4. Process each entry
    for _, entry := range payload.Entry {
        wabaID := entry.ID
        tenant, _ := h.tenantResolver.ResolveByWABAId(ctx, wabaID)  // → Step 3
        for _, change := range entry.Changes {
            h.processChange(ctx, tenant.TenantID, wabaID, &change, payload)  // → Step 4
        }
    }

    w.WriteHeader(200)  // Always return 200 to Meta
}

Step 3: Tenant resolution via admin-service

apps/meta-webhook-service/internal/service/tenant_resolver.go:40-68

Maps a WhatsApp Business Account (WABA) ID to a tenant ID by calling admin-service's internal endpoint.

func (r *TenantResolver) ResolveByWABAId(ctx, wabaID) (*TenantInfo, error) {
    url := fmt.Sprintf("%s/internal/waba/%s/tenant", r.adminServiceURL, wabaID)
    // → GET http://admin-service:8082/internal/waba/waba_123456789/tenant
    resp, _ := r.httpClient.Do(req)
    // Returns: { "tenant_id": "abc-123", "waba_id": "waba_123456789" }
}

Step 4: Event publishing to Kafka

apps/meta-webhook-service/internal/service/event_publisher.go:138-171

Based on the webhook field type, the publisher creates an event and publishes to the appropriate Kafka topic.

// Route by change.Field:
switch change.Field {
case "message_template_status_update":
    // → topic: whatsapp.template.status.v1
    // → event type: whatsapp.template.status_update.v1

case "messages":
    // Statuses → topic: whatsapp.message.status.v1
    // → event type: whatsapp.message.status.v1
    // Messages → topic: whatsapp.message.incoming.v1
}

// Event envelope structure:
event := eventbus.Event{
    ID:       uuid,
    Type:     "whatsapp.message.status.v1",
    Source:   "meta-webhook-service",
    TenantID: "abc-123",
    Data:     MessageStatusPayload{...},  // JSON-serialized
}

Step 5: Broadcast Worker consumes from Kafka

apps/broadcast-service/cmd/worker/main.go:266-276

The broadcast worker subscribes to multiple Kafka topics. Each message is deserialized into an Event envelope and routed to the appropriate handler.

// Worker subscribes to these topics:
consumer.Subscribe("broadcasts.v1", groupID, handler)
consumer.Subscribe("whatsapp.template.status.v1", groupID, metaTemplateHandler)
consumer.Subscribe("whatsapp.message.status.v1", groupID, metaMessageStatusHandler)
consumer.Subscribe("whatsapp.template.quality.v1", groupID, metaTemplateQualityHandler)

// Message status handler:
metaMessageStatusHandler := func(ctx, event) error {
    if event.Type == eventbus.EventTypeWhatsAppMessageStatus {
        metaConsumerSvc.HandleMessageStatusEvent(ctx, event)
        // Updates message delivery status in DB: sent/delivered/read/failed
    }
}

Step 6: Handler processes status update

The MetaConsumerService updates the database record with the new delivery status. For template status updates, it updates the template's approval/rejection status.

// Template status: update template status in DB
//   APPROVED → template is ready to use
//   REJECTED → template needs revision, reason stored

// Message status: update delivery status in broadcast_messages table
//   sent → delivered → read (progressive status)
//   failed → store error code and reason