System Architecture¶
Full Dependency Map¶
Legend
:blue_square: Internal business function · :orange_square: External service (blackbox)
graph LR
CheckWarehouseStock(["Warehouse / CheckWarehouseStock"]):::service
CheckCustomsClearance(["CustomsAPI / CheckCustomsClearance"]):::service
FetchZoneMapping(["GeoService / FetchZoneMapping"]):::service
FetchCarrierRates(["CarrierAPI / FetchCarrierRates"]):::service
estimate_delivery["estimate_delivery"]:::func
calculate_shipping_rate["calculate_shipping_rate"]:::func
compare_shipping_options["compare_shipping_options"]:::func
estimate_delivery -->|.call| CheckWarehouseStock
estimate_delivery -->|.call| FetchZoneMapping
estimate_delivery -->|.call| CheckCustomsClearance
calculate_shipping_rate -->|.call| FetchZoneMapping
calculate_shipping_rate -->|.call| FetchCarrierRates
compare_shipping_options --> calculate_shipping_rate
classDef service fill:#fff3e0,stroke:#e65100,stroke-width:2px,color:#e65100
classDef func fill:#e3f2fd,stroke:#1565c0,stroke-width:2px,color:#1565c0Focus: Delivery Estimation¶
Legend
:green_square: estimate_delivery — entry point · :blue_square: Internal business function · :orange_square: External service (blackbox)
graph LR
estimate_delivery["estimate_delivery"]:::entry
CheckCustomsClearance(["CustomsAPI / CheckCustomsClearance"]):::service
CheckWarehouseStock(["Warehouse / CheckWarehouseStock"]):::service
FetchZoneMapping(["GeoService / FetchZoneMapping"]):::service
estimate_delivery -->|.call| CheckWarehouseStock
estimate_delivery -->|.call| FetchZoneMapping
estimate_delivery -->|.call| CheckCustomsClearance
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:#2e7d32Focus: Rate Comparison¶
Legend
:green_square: compare_shipping_options — entry point · :blue_square: Internal business function · :orange_square: External service (blackbox)
graph LR
compare_shipping_options["compare_shipping_options"]:::entry
FetchCarrierRates(["CarrierAPI / FetchCarrierRates"]):::service
FetchZoneMapping(["GeoService / FetchZoneMapping"]):::service
calculate_shipping_rate["calculate_shipping_rate"]:::func
calculate_shipping_rate -->|.call| FetchZoneMapping
calculate_shipping_rate -->|.call| FetchCarrierRates
compare_shipping_options --> calculate_shipping_rate
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:#2e7d32Rate Calculation Flow¶
flowchart TD
A[Shipping Request] --> B[Lookup Zone]
B --> C{Cross-border?}
C -->|Yes| D[Check Customs]
C -->|No| E[Get Carrier Rates]
D -->|Restricted| F[CANNOT SHIP]
D -->|Clear| E
E --> G[Base Rate]
G --> H[+ Fuel Surcharge 8%]
H --> I{Weight > 5kg?}
I -->|Yes| J[+ Weight Surcharge]
I -->|No| K[No weight surcharge]
J --> L{Zone > 3?}
K --> L
L -->|Yes| M[+ Zone Surcharge]
L -->|No| N[Final Total]
M --> N
style F fill:#ffcdd2,stroke:#c62828,color:#b71c1c
style N fill:#c8e6c9,stroke:#2e7d32,color:#1b5e20
Delivery Sequence¶
PlantUML Source
@startuml
actor Shipper
participant "Shipping System" as sys
participant "Geo Service" as geo
participant "Carrier API" as carrier
participant "Warehouse" as wh
participant "Customs API" as customs
Shipper -> sys : estimate_delivery(product_id, dest_zip)
sys -> wh : CheckWarehouseStock(product_id, dest_zip)
wh --> sys : {in_stock, warehouse_zip, processing_days}
sys -> geo : FetchZoneMapping(warehouse_zip, dest_zip)
geo --> sys : {zone, cross_border}
alt Cross-border shipment
sys -> customs : CheckCustomsClearance(origin, dest, value)
customs --> sys : {clearance_days, restricted}
end
sys -> carrier : FetchCarrierRates(zone, weight, service)
carrier --> sys : {base_rate, fuel_surcharge}
sys -> sys : Calculate total cost & delivery estimate
sys --> Shipper : {total, delivery_days}
@endumlExternal Services¶
Geo Service¶
class FetchZoneMapping(ExternalService):
"""Look up shipping zone from origin/destination postal codes (Blackbox)."""
component_name = "GeoService"
def execute(self, origin_zip: str, dest_zip: str) -> ZoneInfo:
pass # type: ignore[return-value]
def mock(self, origin_zip: str, dest_zip: str) -> MockResponse:
return MockResponse(data=ZoneInfo(
zone=4,
distance_km=850,
cross_border=False,
origin_country="US",
dest_country="US",
))
Carrier API¶
class FetchCarrierRates(ExternalService):
"""Get real-time rates from carrier API (Blackbox)."""
component_name = "CarrierAPI"
def execute(self, zone: int, weight_kg: float, service_level: str) -> CarrierRate:
pass # type: ignore[return-value]
def mock(self, zone: int, weight_kg: float, service_level: str) -> MockResponse:
base_rates = {"standard": 5.99, "express": 12.99, "overnight": 24.99}
base = base_rates.get(service_level, 9.99)
return MockResponse(data=CarrierRate(
base_rate=base,
fuel_surcharge=round(base * 0.08, 2),
carrier="FastShip",
))
Warehouse¶
class CheckWarehouseStock(ExternalService):
"""Check stock availability at the nearest warehouse (Blackbox)."""
component_name = "Warehouse"
def execute(self, product_id: str, dest_zip: str) -> WarehouseStock:
pass # type: ignore[return-value]
def mock(self, product_id: str, dest_zip: str) -> MockResponse:
return MockResponse(data=WarehouseStock(
in_stock=True,
warehouse_zip="10001",
processing_days=1,
))
Customs API¶
class CheckCustomsClearance(ExternalService):
"""Estimate customs processing time for international shipments (Blackbox)."""
component_name = "CustomsAPI"
def execute(self, origin_country: str, dest_country: str, value_usd: float) -> CustomsClearance:
pass # type: ignore[return-value]
def mock(self, origin_country: str, dest_country: str, value_usd: float) -> MockResponse:
return MockResponse(data=CustomsClearance(
clearance_days=0,
duties_applicable=False,
restricted=False,
))