About TradeOps
A multi-tenant warehouse and customs platform for Container Freight Stations, Free Industrial Zones, and Free Commercial Zones. Built on Next.js 16, tRPC v11, Prisma, and PostgreSQL, with an optional AI layer for document extraction, HS classification assistance, demand forecasting, and agent-assisted trade operations.
What this is
Manages the operational and regulatory lifecycle of cargo moving through a CFS or a Free Zone: gate-in, storage, slot allocation, inventory, bonded ledger, declaration prep, duty calculation, gate-out. Multi-tenant by design.
Manufacturing semantics, duty-suspended inputs, exemption tracking, bonded ledger.
Trading semantics, re-export handling, duty-suspension utilisation, gate passes.
Gate-in / gate-out, yard planning, inventory, declaration prep, audit trail.
What this is not
Scope discipline matters more than feature count. These boundaries are deliberate.
Prepares, validates, and audits declarations. Submission to JKDM is via integration, not direct.
Duty, SST, and excise figures are indicative — verify against current Gazette instruments. See SECURITY.md § 2.
Opinionated toward customs-bonded and free-zone operations. For domestic pick-and-pack e-commerce, this is the wrong tool.
Status
What is production-ready, what is beta, and what is explicitly a research spike.
| Aspect | State |
|---|---|
| Core WMS operations | Stable |
| Multi-tenant isolation | Stable |
| RBAC / ABAC | Stable |
| HS classification + duty engine | Stable |
| RAG over cargo documents | Beta |
| Agent mesh orchestration | Beta |
| Digital twin | Experimental |
| Federated learning | Experimental |
| Quantum-hybrid optimisation | Research spike |
"Experimental" and "Research spike" mean exactly that: do not enable them in a production tenant. They are gated behind feature flags and off by default.
Capabilities
Grouped the way operators actually use them — operations, compliance, intelligence, platform.
Operations
- Gate-in / gate-out with weighbridge, ANPR, scanner
- Slot allocation and yard planning
- Inventory with lot, batch, serial tracking
- Cargo lifecycle: consignment → HB → MB → container → package
- Bonded ledger for duty-suspended goods
- FIZ manufacturing and FCZ trading semantics
- Exemption and drawback claim tracking
- Document management with version history
Compliance
- HS classification with an auditable decision trail
- MFN, ATIGA, ACFTA, RCEP, CPTPP, MJEPA, MCFTA resolution
- Duty, SST, and excise — including specific duties
- Controlled-goods and quota flagging (MAQIS, SIRIM, MITI, MDA, DCA)
- Audit log of every human and agent action, with evidence
- Declaration prep and validation; submission is a separate integration
Intelligence (optional)
- Natural-language search over cargo documents and declarations (RAG)
- HS classification suggestions with confidence and citation
- Demand and capacity forecasting
- Anomaly and compliance-risk detection
- Multi-agent workflows for intake, ops reporting, declaration audit
- All high-stakes actions require human approval
Platform
- Pool, silo, and cellular tenancy models
- Per-tenant encryption keys
- SSO / SCIM for enterprise tenants
- Webhooks and event stream for downstream systems
- Feature flags per environment and per tenant
The tariff backbone
Every customs-relevant calculation resolves through a single dataset: src/hs-code-data.ts. Authoritative for HS/AHTN 2022 subheadings, MFN rates, SST, excise, preferential FTA rates, agency control flags, and carbon-tax applicability.
The golden rule: every rate row carries a source and retrievedAt field. A rate with no source is a bug, not a feature. A change that alters a rate without updating its fixture fails CI.
Architecture & intelligence
A single orchestrator is the only entry point for server-side work. Optional AI features are independently gated, and agents are structured capabilities — not free-form chatbots.
Core technologies
- Frontend · Next.js 16 App Router, React 19, Tailwind CSS
- API · NestJS + tRPC v11, MCP at
/api/mcp - Database · PostgreSQL 16, Prisma ORM
- Queue · Redis 7, BullMQ
- Vector · Weaviate (BM25 + vector hybrid)
- AI / ML · LangChain, OpenAI-compatible LLMs, TF.js, ONNX
- Agents · Agent Mesh, FSM routing, contractual tasks
- Edge · Vercel Edge, Cloudflare Workers, on-prem ONNX
Multi-tenancy models
- Pool · shared DB,
tenantIdscoping - Silo · dedicated DB per tenant
- Cellular · isolated data plane per cell, shared control plane
- Prisma extension throws if a tenant-scoped query omits
tenantId - For cellular tenants, the client is bound to the cell's connection string
Agents — scoped, not chatty
Each agent has a kind, an explicit scope list of tRPC procedures it may call, and a guardrail config stating which actions need human approval. High-stakes actions require human approval and cannot be delegated to an agent.
Collaborate
Open to pilots, integrations, and zone-operator partnerships. Read CONTRIBUTING.md before opening a PR. For security issues, see SECURITY.md.