pos-system/docs/en/architecture/multi-vertical-architecture.md

# 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

```mermaid
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.

```mermaid
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

```csharp
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

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

### ShopFeatures (Feature Flags)

```csharp
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:

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

## Data Flow Examples

### Retail Order Flow

```mermaid
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

```mermaid
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 |

## Related Resources

- [Implementation Plan](file:///Users/velikho/.gemini/antigravity/brain/fc592f5c-fd0a-4a19-87d0-d09926a1cdde/implementation_plan.md)
- [Domain-Driven Design Skill](file:///Users/velikho/Desktop/WORKING/Base/.agent/skills/domain-driven-design/SKILL.md)
- [CQRS Pattern Skill](file:///Users/velikho/Desktop/WORKING/Base/.agent/skills/cqrs-mediatr/SKILL.md)
- [Inter-Service Communication](file:///Users/velikho/Desktop/WORKING/Base/.agent/skills/inter-service-communication/SKILL.md)