Operating Model
Internal guide to Helm roles, system boundaries, and the core consignment operating model.
Helm is the operating layer for Xtellar-managed import consignments. It coordinates customer intake, item normalization, HS classification, tax estimation, document generation, forwarder handoff, tracking, payment gates, clearing, delivery, and closure.
Primary actors
| Actor | Internal meaning |
|---|---|
| Customer | Account that owns the consignment and receives portal-visible documents, statuses, and invoices. |
| Xtellar logistics team | Team that creates and reviews consignments, manages exceptions, prepares documents, and controls readiness gates. |
| Freight forwarder | China-side operator that receives only ready consignments and provides shipping documents, waybills, and dispatch status. |
| Accounts team | Team that confirms payment state and coordinates Zoho invoice references. |
| Clearing agent | Xtellar or third party responsible for Uganda customs clearing. |
System boundaries
Helm depends on several external systems:
- Supabase stores customers, consignments, items, documents, tracking events, and status metadata.
- Tarifix tax services classify items and calculate Uganda duties and taxes.
- 17track provides domestic and international shipment tracking.
- Zoho Books handles customer invoice and payment references.
- Supabase cron jobs and background jobs keep exchange rates and tracking data fresh.
- Upstash Redis caches selected expensive API responses, tracking lookups, and estimates.
Do not store credentials, API keys, or private carrier payloads in documentation. Internal docs should describe operational behavior and escalation paths, not secret values.
Readiness gate
A consignment moves from internal preparation to forwarder visibility only after review. The readiness gate exists to prevent incomplete invoice parsing, missing HS codes, unresolved special-item warnings, or incorrect customer data from reaching the forwarder dashboard.
Closure principle
Close a consignment only after delivery, payment confirmation, document availability, and unresolved exception review are complete. Closure is an audit action, not a shipping milestone.