pos-system/services/catalog-service-net/docs/en/ARCHITECTURE.md

Catalog Service Architecture

Architecture documentation for the Catalog Service.

Architecture Overview

graph TB
    subgraph "API Layer"
        C[Controllers]
        CMD[Commands]
        Q[Queries]
    end
    
    subgraph "Domain Layer"
        P[Product Aggregate]
        CAT[Category]
        PT[ProductType]
    end
    
    subgraph "Infrastructure Layer"
        DB[(PostgreSQL)]
        R[ProductRepository]
        CTX[CatalogContext]
    end
    
    C --> CMD
    C --> Q
    CMD --> P
    Q --> R
    R --> CTX --> DB
    
    style P fill:#50c878,stroke:#2d8659,color:#fff
    style DB fill:#ff6b6b,stroke:#c0392b,color:#fff

Layer Responsibilities

Domain Layer

Component	Purpose
Product	Aggregate root with polymorphic attributes
Category	Product categorization
ProductType	Enumeration (Physical, Service, PreparedFood)
ProductVariant	Size, Color, etc.

Infrastructure Layer

Component	Purpose
CatalogContext	EF Core DbContext with JSONB support
ProductRepository	Product persistence
CategoryRepository	Category persistence

Database Schema

erDiagram
    products {
        uuid id PK
        uuid shop_id FK
        varchar name
        decimal price
        varchar product_type
        jsonb attributes
        boolean is_active
        timestamp created_at
    }
    
    categories {
        uuid id PK
        uuid shop_id FK
        varchar name
        uuid parent_id FK
    }
    
    product_categories {
        uuid product_id FK
        uuid category_id FK
    }
    
    products ||--o{ product_categories : has
    categories ||--o{ product_categories : contains
    categories ||--o{ categories : parent

JSONB Attributes by Product Type

Physical Product

{
  "weight": 0.5,
  "dimensions": { "length": 30, "width": 20, "height": 5 },
  "sku": "TSH-001-BLK-M",
  "barcode": "1234567890123"
}

Service Product

{
  "durationMinutes": 60,
  "staffRequired": true,
  "resourceType": "Room"
}

PreparedFood Product

{
  "recipeId": "uuid",
  "kitchenStation": "Bar",
  "toppings": ["Extra shot", "Oat milk"],
  "preparationTime": 5
}

Integration Points

sequenceDiagram
    participant ORDER as Order Service
    participant CATALOG as Catalog Service
    participant MERCHANT as Merchant Service
    
    ORDER->>CATALOG: Get Product Details
    CATALOG->>MERCHANT: Validate Shop Access
    MERCHANT-->>CATALOG: Shop Features
    CATALOG-->>ORDER: Product with Type & Attributes

References

• Multi-vertical Architecture
• eShopOnContainers