Lab 001: Encapsulating Enterprise Systems with Claude Code

I am building the foundation for an enterprise AI application that will be extended across multiple implementation labs. The project implements a modern version of an enterprise order fulfillment process inspired by classic business process orchestration (BPO/BSO) systems.

The purpose of this lab is to demonstrate the enterprise architecture principle of encapsulation. These modules represent stable service boundaries around enterprise systems. They intentionally hide implementation complexity behind simple interfaces because later labs will orchestrate these services rather than interact with their internal implementations.

The working directory is:

order-fulfillment-ai

Create the following project structure:

order-fulfillment-ai/
└── stubs/
    ├── __init__.py
    ├── contract_store.py
    ├── erp_system.py
    ├── po_generator.py
    └── warehouse_system.py

Follow these conventions throughout the project:

• Use Python 3.11.
• Use only the Python standard library unless explicitly instructed otherwise.
• Include type hints on all public functions.
• Add concise module and function docstrings.
• Keep implementations intentionally simple and easy to understand.
• Do not introduce classes unless specifically requested.
• Do not introduce dependency injection, configuration frameworks, logging frameworks, or unnecessary abstractions.
• Keep each function focused on a single responsibility.
• Generate realistic enterprise data suitable for later AI reasoning.
• Use Python's random module for simulated behavior.
• Centralize random generation so deterministic testing can be introduced later by setting a random seed.
• Do not create any files beyond those explicitly requested.

--------------------------------------------------------------------
stubs/erp_system.py
--------------------------------------------------------------------

Simulate a SAP-like ERP back-end system.

Define a custom exception:

OrderCreationError

Implement the following public functions.

create_order(po: dict) -> dict

Accept a purchase order dictionary.

Return:

• order_id (string formatted like ORD-XXXXX)
• confirmed_quantity (integer)
• estimated_ship_date (ISO date string)

Simulate realistic enterprise failures by raising OrderCreationError on approximately 10% of calls.

Example failure reasons include:

• Vendor on credit hold
• Inventory unavailable
• Material allocation failure
• ERP timeout
• Invalid purchasing organization

get_service_level(order_id: str, requested_delivery_date: str) -> dict

Return:

• committed_date (ISO date string)
• confidence_score (float between 0.65 and 0.98)
• available_quantity (integer)

The committed delivery date should occasionally be 2–5 days later than requested.

Available quantity should occasionally be less than requested.

get_invoice(order_id: str) -> dict

Return:

• invoice_id
• line_items
    • part_number
    • description
    • quantity
    • unit_price
    • extended_amount
• subtotal
• tax
• total

On approximately 20% of calls, introduce a realistic pricing variance between 3% and 7% above the expected unit price. These anomalies will be detected by AI in later labs.

--------------------------------------------------------------------
stubs/warehouse_system.py
--------------------------------------------------------------------

Implement the following public functions.

create_shipping_manifest(order_id: str, items: list) -> dict

Return:

• manifest_id (MFT-XXXXX)
• carrier (FedEx, UPS, or DHL)
• estimated_arrival (ISO date string)
• item_list

notify_dispatch(manifest_id: str) -> dict

Return:

• tracking_number (12-digit string)
• dispatch_timestamp (ISO datetime)

record_material_acceptance(
    manifest_id: str,
    accepted_items: list,
    qa_notes: str
) -> dict

Return:

• acceptance_id
• recorded_at
• status ("recorded")

--------------------------------------------------------------------
stubs/contract_store.py
--------------------------------------------------------------------

Implement one public function.

get_contracts() -> list[str]

Generate five realistic enterprise procurement contracts.

Each contract should be approximately 500–1000 words and resemble an actual supplier agreement.

Each contract represents one product category:

• Steel Components
• Electronic Assemblies
• Plastic Moldings
• Fasteners
• Precision Machined Parts

Each contract should include clearly identifiable sections covering:

• Unit pricing schedules
• Delivery service level agreements
• Quality acceptance standards
• Material inspection procedures
• Late delivery penalties
• Invoice validation requirements
• Invoice dispute procedures
• Payment terms
• Escalation procedures
• Termination clauses

The contracts should read like real legal procurement documents rather than sample text.

--------------------------------------------------------------------
stubs/po_generator.py
--------------------------------------------------------------------

Implement two public functions.

generate_po() -> dict

Return a realistic purchase order containing:

• po_number (PO-XXXXX)
• vendor_id
• vendor_name
• line_items (2–4 items)

Each line item includes:

• part_number
• description
• quantity
• unit_price
• parts_category

Also include:

• requested_delivery_date (ISO date string)
• cost_center

Occasionally generate aggressive delivery requests only 3–5 days in the future.

Ensure purchase orders are internally consistent with the vendors, product categories, and contracts generated in contract_store.py.

generate_batch(n: int) -> list

Return a list containing n purchase orders.

--------------------------------------------------------------------
stubs/__init__.py
--------------------------------------------------------------------

Import all four modules so they are available as:

stubs.erp_system
stubs.warehouse_system
stubs.contract_store
stubs.po_generator

--------------------------------------------------------------------
Completion Requirements
--------------------------------------------------------------------

When finished:

• Verify that every module imports successfully.
• Ensure all generated code is syntactically correct.
• Ensure every public function includes a concise docstring.
• Provide a brief summary of each file that was created.
• Do not create additional files beyond those requested.
• Do not explain your implementation unless errors occur.

find stubs -type f | sort

stubs/
  __init__.py
  contract_store.py
  erp_system.py
  po_generator.py
  warehouse_system.py

python3.11 - <<'EOF'
from stubs import (
    contract_store,
    erp_system,
    po_generator,
    warehouse_system,
)

print("Imports successful")
EOF

Imports successful

python3.11 - <<'EOF'
from pprint import pprint
from stubs.po_generator import generate_po

pprint(generate_po())
EOF

{'cost_center': 'CC-2100',
 'line_items': [{'description': 'ABS Enclosure Shell',
                 'part_number': 'PN-4253',
                 'parts_category': 'Plastic Moldings',
                 'quantity': 184,
                 'unit_price': 14.01},
                {'description': 'ABS Enclosure Shell',
                 'part_number': 'PN-7390',
                 'parts_category': 'Plastic Moldings',
                 'quantity': 42,
                 'unit_price': 44.97},
                {'description': 'Polycarbonate Cover Panel',
                 'part_number': 'PN-8558',
                 'parts_category': 'Plastic Moldings',
                 'quantity': 356,
                 'unit_price': 47.01}],
 'po_number': 'PO-40935',
 'requested_delivery_date': '2026-07-28',
 'vendor_id': 'VEND-1003',
 'vendor_name': 'Polyform Industries Inc.'}

python3.11 - <<'EOF'
from stubs import erp_system, po_generator

po = po_generator.generate_po()

print(erp_system.create_order(po))
EOF

{
    'order_id': 'ORD-48172',
    'confirmed_quantity': 14,
    'estimated_ship_date': '2026-07-05'
}

for i in $(seq 1 20); do
python3.11 - <<'EOF'
from stubs import erp_system, po_generator

po = po_generator.generate_po()

try:
    print(erp_system.create_order(po)["order_id"])
except Exception as e:
    print("ERROR:", e)
EOF
done

ORD-82421
ORD-49694
ORD-61417
ORD-56933
ORD-64642
ORD-94860
ORD-95764
ORD-51939
ERROR: Material allocation failure
ORD-75615
ORD-71835
ORD-54683
ORD-43077
ORD-87169
ERROR: Material allocation failure
ORD-44349
ORD-41829
ORD-43903
ORD-82424
ORD-23674

python3.11 - <<'EOF'
from stubs import erp_system

print(
    erp_system.get_service_level(
        "ORD-12345",
        "2026-07-01"
    )
)
EOF

{'committed_date': '2026-07-01', 'confidence_score': 0.87, 'available_quantity': 52}

python3.11 - <<'EOF'
from pprint import pprint
from stubs import erp_system

pprint(
    erp_system.get_invoice("ORD-12345")
)
EOF

{'invoice_id': 'INV-384519',
 'line_items': [{'description': 'Hex Bolt, Zinc Plated',
                 'extended_amount': 22340.86,
                 'part_number': 'PN-3459',
                 'quantity': 142,
                 'unit_price': 157.33},
                {'description': 'Circuit Board Module',
                 'extended_amount': 9534.96,
                 'part_number': 'PN-5744',
                 'quantity': 114,
                 'unit_price': 83.64},
                {'description': 'Hex Bolt, Zinc Plated',
                 'extended_amount': 1325.82,
                 'part_number': 'PN-4417',
                 'quantity': 19,
                 'unit_price': 69.78},
                {'description': 'Circuit Board Module',
                 'extended_amount': 31428.0,
                 'part_number': 'PN-5994',
                 'quantity': 180,
                 'unit_price': 174.6}],
 'subtotal': 64629.64,
 'tax': 4847.22,
 'total': 69476.86}

python3.11 - <<'EOF'
from pprint import pprint
from stubs import warehouse_system

manifest = warehouse_system.create_shipping_manifest(
    "ORD-12345",
    [{"part_number": "ABC", "quantity": 10}]
)

pprint(manifest)

dispatch = warehouse_system.notify_dispatch(
    manifest["manifest_id"]
)

pprint(dispatch)
EOF

{'carrier': 'FedEx',
 'estimated_arrival': '2026-07-05',
 'item_list': [{'part_number': 'ABC', 'quantity': 10}],
 'manifest_id': 'MFT-98740'}
{'dispatch_timestamp': '2026-06-30T17:17:21.782635',
 'tracking_number': '498525603858'}

python3.11 - <<'EOF'
from stubs.contract_store import get_contracts

contracts = get_contracts()

print(len(contracts))
print(len(contracts[0].split()))
EOF

5
835