Design Container Assignment with Incompatible Goods

Scenario

In ocean freight consolidation, freight forwarders pack cargo bookings from multiple shippers into standardized ocean containers (e.g., 20ft/40ft standard, high-cube, reefer). Items vary by dimensions, weight, stackability, and regulatory classifications (such as IMDG hazardous material classes). Certain goods cannot be co-loaded in the same container (e.g., flammable liquids cannot be placed with oxidizers or food products).

Design a container-assignment planning service that assigns cargo to containers while minimizing total container costs, enforcing hard physical and safety constraints, and allowing human operators to inspect, override, and approve plans.

Requirements

Functional Requirements

• Optimization & Constraint Enforcement: Given a manifest of cargo items and available container types, compute container assignments satisfying volume, weight capacity, and pairwise/group incompatibility rules.
• Asynchronous Planning: Optimization jobs must run asynchronously with polling or webhook notifications for status.
• Deterministic Results: Given the exact same inputs (manifest, container types, rule versions, and configuration seed), the solver must produce identical container assignments.
• Explainable Infeasibility: If a set of items cannot be legally or physically packed, the service must return actionable explanations identifying the conflicting items or violated constraints.
• Drafts, Overrides, and Approvals: Generated plans are saved as drafts. Operators can manually move items between containers (validated against safety constraints) and approve the final plan.
• Stale-Input Protection & Concurrency: Prevent approving or finalizing a plan if underlying cargo details changed during solver execution or operator review.
• Auditability: Maintain an immutable history of input revisions, solver outputs, manual edits, and approval actions.

Non-Functional Requirements & Scale

• Scale: 15,000 shipment planning requests per day; up to 100 concurrent optimization runs.
• Job Size: Typical plans contain 50 to 500 items; large multi-supplier consolidations contain up to 5,000 items.
• Execution Time: Under 30 seconds for standard plans (p95); under 2 minutes for 5,000-item plans.
• Data Consistency: Strict consistency on plan approvals and inventory locking to prevent double-allocating cargo or containers.

What Your Design Should Cover

1. API Design: Key endpoints for submitting plan requests, checking progress, retrieving explanations, overriding assignments, and approving plans.
2. Data Model: Schemas representing Cargo Items, Incompatibility Rules, Container Specs, Plans, Assignments, and Audit Logs.
3. Architecture: Decoupled async job processing, solver workers (e.g., integer programming/constraint programming), and caching/storage tiers.
4. Concurrency & Correctness: Handling race conditions between concurrent operator edits and manifest updates using optimistic concurrency control (OCC) or hashing.
5. Explainability & Conflict Resolution: Strategy for identifying minimal conflicting subsets when a manifest cannot be fully packed.