AI-Ready System Architecture

Defined Pydantic models for Supplier, Product, and Order with hard validation rules: SKU format enforced by regex, stock values non-negative, supplier reliability bounded 0–1, order status constrained to a fixed state machine. Invalid states cannot be created. The system rejects malformed data at the boundary before it reaches business logic.

Three domain invariants were formalized: stock allocation safety (confirmed orders cannot exceed available stock), upper bound constraint (inbound replenishment cannot exceed thresholds without an explicit override workflow), and shipped immutability (a shipped order cannot be reversed except through a compensating workflow). The service layer enforces them. The database guarantees them.

Refactored from a monolithic API into three layers with hard separation of concerns. The repository layer handles data access — no HTTP exceptions, no business rules. The service layer enforces all business logic via domain-specific exceptions — no HTTP concepts. The router layer handles HTTP translation only — no business logic, exception mapping to status codes exclusively.

Five custom domain exceptions form the explicit contract between layers. The storage engine swapped from in-memory dictionaries to SQLite without touching the service or router layers. The architecture absorbed it.

Explicit directed graph with terminal states (shipped, cancelled) and valid transitions only: drafted → confirmed → shipped or cancelled. Invalid transitions return 409. The state machine maps directly to LangGraph node transitions — the business workflow and the agent workflow use the same logic.

SQLite and SQLAlchemy replaced in-memory storage without touching the service or router layers. A supplier-product junction table encodes which suppliers can fulfill which SKUs. Order creation validates that the specified supplier supplies the requested product — the system rejects the pairing if it does not exist. Referential integrity is structural.

A LangGraph ReorderAgent runs four nodes: fetch products below threshold, propose reorders via ranked supplier recommendations, generate a plain-language HITL narrative via LLM, pause for operator approval before committing orders. The LLM executes only at judgment boundaries — unstructured input, no deterministic ground truth. Reorder calculation, stock comparison, status transitions, and referential validation run in Python.

The commit node does not execute without explicit operator approval. This is a design principle, not a prototype limitation. LangChain was rejected in favor of a provider-isolated interface — the agent is ignorant of which model is active.

Suppliers carry an ISO 3166-1 country field. A standalone script queries GDELT for risk-relevant news per country. The LLM receives structured supplier-country-news data and reasons across it — one API call per country, not per supplier. The LLM dismisses irrelevant articles rather than hallucinating risks. Verified against Taiwan cross-strait coverage tied to a specific supplier in the seed data.