Files

Ho Ngoc Hai 76d75c753b Migrate

2026-05-23 18:37:02 +07:00

6.2 KiB

Raw Permalink Blame History

Multi-vertical Architecture Design

Overview

This document describes the architectural approach for supporting multi-vertical business operations in the GoodGo platform. The design enables a single Merchant to operate across multiple business verticals (Retail, F&B, Services) without creating tightly-coupled "spaghetti code."

Design Principle

Merchant Service manages "WHO" (Identity) and "RULES" (Configuration), while "HOW" (Execution) is delegated to satellite services.

Architecture Layers

graph TB
    subgraph Clients ["📱 Client Layer"]
        POS["Smart POS"]
        WEB["Web Dashboard"]
        APP["Mobile App"]
    end

    subgraph Gateway ["⚡ API Gateway"]
        TRAEFIK["Traefik"]
    end

    subgraph Core ["🟡 Core Layer - Identity & Configuration"]
        IAM["🔐 IAM Service"]
        MERCHANT["🏪 Merchant Service"]
        WALLET["💰 Wallet Service"]
    end

    subgraph Orchestration ["🔴 Orchestration Layer"]
        CATALOG["📦 Catalog Service"]
        ORDER["📝 Order Service"]
    end

    subgraph Verticals ["🔵 Vertical Engines"]
        INVENTORY["🏭 Inventory"]
        BOOKING["📅 Booking"]
        FNB["🍳 F&B Engine"]
    end

    Clients --> Gateway
    Gateway --> Core
    Gateway --> Orchestration
    ORDER --> Verticals

Layer Responsibilities

1. Core Layer (Configuration & Identity)

Service	Responsibility
IAM Service	User authentication, roles, permissions
Merchant Service	Shop identity, feature flags, business settings
Wallet Service	Payment processing, balance management

2. Orchestration Layer

Service	Responsibility
Catalog Service	Polymorphic product management
Order Service	Order processing with Strategy Pattern

3. Vertical Engines

Service	Vertical	Core Logic
Inventory Service	Retail, F&B	Stock management, recipes
Booking Service	Services	Appointment scheduling
F&B Engine	Food & Beverage	Tables, sessions, kitchen display

Strategy Pattern for Order Processing

The Order Service acts as the "brain" that routes each line item to the appropriate vertical engine based on product type.

flowchart LR
    ORDER["Order Service"]
    
    subgraph Strategies ["Line Item Strategies"]
        RETAIL["RetailStrategy"]
        SERVICE["ServiceStrategy"]
        FNB["FnbStrategy"]
    end
    
    ORDER --> |"ProductType.Physical"| RETAIL
    ORDER --> |"ProductType.Service"| SERVICE
    ORDER --> |"ProductType.PreparedFood"| FNB
    
    RETAIL --> INVENTORY["Inventory Service"]
    SERVICE --> BOOKING["Booking Service"]
    FNB --> KITCHEN["F&B Engine"]

Strategy Interface

public interface ILineItemStrategy
{
    ProductType SupportedType { get; }
    Task ValidateAsync(OrderItem item, Guid shopId);
    Task ExecuteAsync(OrderItem item, Guid shopId);
}

Hybrid Order Support

A single order can contain multiple product types:

☕ Coffee (PreparedFood → F&B Engine)
👕 Merchandise T-shirt (Physical → Inventory Service)
💆 Spa voucher (Service → Booking Service)

Each line item is processed by its corresponding strategy.

Merchant Service Configuration Model

BusinessCategory Enum

public enum BusinessCategory
{
    Retail = 1,       // Physical goods
    FoodBeverage = 2, // Restaurants, cafes
    Services = 3,     // Spa, salon, clinic
    Other = 99        // Hybrid
}

ShopFeatures (Feature Flags)

public record ShopFeatures(
    bool HasInventory = false,  // Enable Inventory Service
    bool HasBooking = false,    // Enable Booking Service
    bool HasTables = false,     // Enable table management
    bool HasKitchen = false,    // Enable KDS
    bool HasShipping = false,   // Enable shipping
    bool HasDelivery = false    // Enable delivery
);

Dynamic Settings (JSONB)

Business-specific parameters stored as JSON:

{
  "fnb": {
    "serviceChargePercent": 5,
    "defaultTableCapacity": 4
  },
  "booking": {
    "slotDurationMinutes": 30,
    "advanceBookingDays": 14
  },
  "retail": {
    "lowStockThreshold": 10
  }
}

Data Flow Examples

Retail Order Flow

sequenceDiagram
    participant POS
    participant Order as Order Service
    participant Merchant as Merchant Service
    participant Inventory as Inventory Service
    participant Wallet as Wallet Service

    POS->>Order: Create Order (Physical item)
    Order->>Merchant: Get ShopFeatures
    Merchant-->>Order: {HasInventory: true}
    Order->>Inventory: Validate stock
    Inventory-->>Order: Stock OK
    Order->>Wallet: Process payment
    Wallet-->>Order: Payment success
    Order->>Inventory: Deduct stock
    Order-->>POS: Order completed

F&B Order Flow

sequenceDiagram
    participant POS
    participant Order as Order Service
    participant FnB as F&B Engine
    participant Inventory as Inventory Service

    POS->>Order: Create Order (Table 5, Coffee)
    Order->>FnB: Add to active session
    FnB->>FnB: Create KitchenTicket
    FnB-->>Order: Ticket created
    Note over FnB: Display on KDS
    FnB->>Inventory: Deduct ingredients (optional)
    Order-->>POS: Order confirmed

Benefits of This Architecture

Benefit	Description
Single Responsibility	Each service handles one domain
Extensibility	Add new verticals without modifying core
Testability	Strategies are independently testable
Hybrid Support	Mixed orders handled naturally
Configuration-Driven	Behavior changes via feature flags

6.2 KiB Raw Permalink Blame History