Skip to content

System Architecture

Full Dependency Map

Legend

:blue_square: Internal business function · :orange_square: External service (blackbox)

graph LR
    CheckInventory(["Warehouse / CheckInventory"]):::service
    ProcessPayment(["PaymentGateway / ProcessPayment"]):::service
    FetchProductCatalog(["ProductCatalog / FetchProductCatalog"]):::service
    FetchCustomerTier(["CustomerService / FetchCustomerTier"]):::service
    validate_order["validate_order"]:::func
    process_order["process_order"]:::func
    calculate_line_price["calculate_line_price"]:::func
    calculate_order_total["calculate_order_total"]:::func
    validate_order --> calculate_order_total
    validate_order -->|.call| CheckInventory
    process_order --> validate_order
    process_order -->|.call| ProcessPayment
    calculate_line_price -->|.call| FetchProductCatalog
    calculate_order_total -->|.call| FetchCustomerTier
    calculate_order_total --> calculate_line_price

    classDef service fill:#fff3e0,stroke:#e65100,stroke-width:2px,color:#e65100
    classDef func fill:#e3f2fd,stroke:#1565c0,stroke-width:2px,color:#1565c0

Focus: Order Processing Pipeline

Legend

:green_square: process_order — entry point · :blue_square: Internal business function · :orange_square: External service (blackbox)

graph LR
    process_order["process_order"]:::entry
    CheckInventory(["Warehouse / CheckInventory"]):::service
    FetchCustomerTier(["CustomerService / FetchCustomerTier"]):::service
    FetchProductCatalog(["ProductCatalog / FetchProductCatalog"]):::service
    ProcessPayment(["PaymentGateway / ProcessPayment"]):::service
    calculate_line_price["calculate_line_price"]:::func
    calculate_order_total["calculate_order_total"]:::func
    validate_order["validate_order"]:::func
    validate_order --> calculate_order_total
    validate_order -->|.call| CheckInventory
    process_order --> validate_order
    process_order -->|.call| ProcessPayment
    calculate_line_price -->|.call| FetchProductCatalog
    calculate_order_total -->|.call| FetchCustomerTier
    calculate_order_total --> calculate_line_price

    classDef service fill:#fff3e0,stroke:#e65100,stroke-width:2px,color:#e65100
    classDef func fill:#e3f2fd,stroke:#1565c0,stroke-width:2px,color:#1565c0
    classDef entry fill:#e8f5e9,stroke:#2e7d32,stroke-width:3px,color:#2e7d32

Order Pipeline

flowchart TD
    A[New Order] --> B[Check Inventory]
    B -->|All in stock| C[Calculate Pricing]
    B -->|Items unavailable| D[ORDER REJECTED]
    C --> E[Apply Volume Discounts]
    E --> F[Apply Loyalty Discount]
    F --> G[Process Payment]
    G -->|Payment OK| H[ORDER CONFIRMED]
    G -->|Payment Failed| I[PAYMENT FAILED]

    style H fill:#c8e6c9,stroke:#2e7d32,color:#1b5e20
    style D fill:#ffcdd2,stroke:#c62828,color:#b71c1c
    style I fill:#fff3e0,stroke:#e65100,color:#bf360c

Sequence Diagram

PlantUML diagram
PlantUML Source 
@startuml
actor Customer
participant "Order System" as sys
participant "Warehouse" as wh
participant "Product Catalog" as cat
participant "Customer Service" as cs
participant "Payment Gateway" as pay

Customer -> sys : process_order(items, payment)

loop For each item
    sys -> wh : CheckInventory(product_id)
    wh --> sys : {available, stock}
end

sys -> cat : FetchProductCatalog(product_id)
cat --> sys : {name, base_price}

sys -> cs : FetchCustomerTier(customer_id)
cs --> sys : {tier: "gold", discount: 10%}

sys -> sys : Calculate total with discounts

sys -> pay : ProcessPayment(amount)
pay --> sys : {status: "captured", txn_id}

sys --> Customer : Order CONFIRMED
@enduml

External Services

Product Catalog

class FetchProductCatalog(ExternalService):
    """Retrieve product details from the catalog service (Blackbox)."""

    component_name = "ProductCatalog"

    def execute(self, product_id: str) -> ProductInfo:
        pass  # type: ignore[return-value]

    def mock(self, product_id: str) -> MockResponse:
        return MockResponse(data=ProductInfo(
            id=product_id,
            name="Wireless Headphones",
            base_price=79.99,
            category="electronics",
        ))

Customer Service

class FetchCustomerTier(ExternalService):
    """Retrieve customer loyalty tier (Blackbox)."""

    component_name = "CustomerService"

    def execute(self, customer_id: str) -> CustomerTier:
        pass  # type: ignore[return-value]

    def mock(self, customer_id: str) -> MockResponse:
        return MockResponse(data=CustomerTier(
            tier="gold",
            discount_pct=10,
            member_since="2022-03-15",
        ))

Warehouse

class CheckInventory(ExternalService):
    """Check product availability in the warehouse (Blackbox)."""

    component_name = "Warehouse"

    def execute(self, product_id: str) -> StockInfo:
        pass  # type: ignore[return-value]

    def mock(self, product_id: str) -> MockResponse:
        return MockResponse(data=StockInfo(
            available=True,
            stock=250,
            warehouse="EU-WEST-1",
        ))

    def mock_error(self, product_id: str) -> MockErrorResponse:
        return MockErrorResponse(
            error_code="WAREHOUSE_TIMEOUT",
            error_message="Warehouse service did not respond in time.",
            http_code=504,
        )

Payment Gateway

class ProcessPayment(ExternalService):
    """Submit payment to the payment gateway (Blackbox)."""

    component_name = "PaymentGateway"

    def execute(self, payment_data: dict) -> PaymentResult:
        pass  # type: ignore[return-value]

    def mock(self, payment_data: dict) -> MockResponse:
        return MockResponse(data=PaymentResult(
            status="captured",
            transaction_id="txn_abc123",
            amount=payment_data.get("amount", 0),
        ))

    def mock_error(self, payment_data: dict) -> MockErrorResponse:
        return MockErrorResponse(
            error_code="PAYMENT_DECLINED",
            error_message="Card was declined by the issuing bank.",
            http_code=402,
        )