Cross-Border Logistics Platform

The platform manages US–Vietnam cross-border parcels end to end: pickup, warehouse consolidation into flight batches, and final-mile delivery in Vietnam. Customers — primarily the Vietnamese diaspora in the US — create orders online and track shipments publicly, while admin staff run bulk CRUD, batch status changes and document generation (PDF, thermal labels).

The architectural through-line is keeping a genuinely complex logistics domain simple: a shipment's state is derived from date milestones rather than a separate state machine, notifications run async off the request path, and compliance is met with soft deletes plus append-only audit logs instead of a heavier records subsystem.

Cross-border parcel shipping carries real domain complexity — multi-leg movement across two countries, region-specific notification rules, and legal retention obligations — but the business needed fast feature delivery at mid scale, not a distributed rewrite.

Constraints

• A shipment moves through several stages (US receipt → flight → VN receipt → delivery); the model must reflect this without an over-engineered state machine.
• Customer notifications span two regions with different phone conventions; US and VN SMS must route differently.
• Notification providers (SMS/email) are slow and occasionally fail; they must never block a shipment status update.
• Vietnamese tax/audit expectations require retaining deleted orders and preserving an immutable trail of status transitions.
• Addresses change over time, but a shipment's destination must stay locked to what it was at order time.

• hoadons — main shipment record: tracking_number, package_number, and four date milestones (ngaynhan_us, ngay_chuyen_hang, ngaynhan_vn, ngaygiao) that together imply the current state
• online_orders — customer-submitted orders with denormalized address fields and soft-delete support
• hoadon_masters — flight-batch groupings; shipments are aggregated and tracked as a unit
• addresses — normalized customer address book with a default per customer
• log_hoadons — immutable audit log of status transitions
• online_order_jobs — audit trail of notification jobs dispatched to customers
• users — customers and admin staff
• blacklists — blocked/fraud customer list

Denormalization pattern: shipping address fields (name, address, city, state, zip, country, mobile) are copied into the order alongside the normalized address foreign key, so the destination is locked at order time and reads stay index-friendly.

Reads: Redis caches public tracking lookups so the highest-volume, unauthenticated traffic is served without hammering MySQL; DB read replicas are the next lever if needed.

Notifications: async jobs decouple SMS/email from request–response, and the Redis queue can be swapped for a distributed broker (SQS, RabbitMQ, Beanstalkd) as notification volume grows.

Retention & recovery: soft deletes keep history queryable without purging, and daily spatie/laravel-backup snapshots provide a recovery path. The monolith is sized to grow toward 100K+ orders/month before a service split becomes worthwhile.