Control center
Free Commercial Zone (FCZ) walkthrough
FCZ organizes commercial-zone work across entrepot, transhipment, break-bulk, re-export, repackaging, value-add, trading houses and analytics. Its route components query dedicated fcz routers for several list/detail views and mutations; confirm the specific resource route before assuming every page has the same persistence support.
Key routes
- FCZ overview
Entry point to FCZ work areas.
- Transhipment
Browse FCZ transhipment records.
- Break-bulk
Browse break-bulk records and creation flow.
- Entrepot
Review entrepot records and matching route.
- Re-export
Browse re-export records and creation flow.
- Trading houses
Browse trading-house records.
- Analytics
Review FCZ summary views.
Prerequisites and seed data
- Sign in with the tenant that owns the FCZ records.
- Seed or create FCZ transhipment, break-bulk, entrepot, re-export or trading-house records through the supported forms.
- Use appropriate broker/operator authority and verified shipment/document references for customs-controlled operations.
Primary workflows
Register a transhipment
Review the queue, create a record where the form is available, and inspect the selected record.
- Open the transhipment list and confirm the target shipment is not already registered. Transhipment
- Use the new flow to enter verified movement details. New transhipment
- Return to the list and select the record to view its detail. Transhipment
Process commercial-zone stock
Use entrepot records and matches as the available cross-reference surfaces.
- Review entrepot records for the relevant goods or transaction. Entrepot
- Open the match view to inspect possible record matches. Entrepot matches
- Use the re-export route when the approved workflow requires outward movement. Re-export
Review value-added work
Locate repackaging and value-add routes for work beyond storage and movement.
- Open repackaging jobs and create a job only through the supported form. Repackaging
- Review value-add activity and analytics for the resulting work. Value-add
Concepts
- Entrepot
- A commercial-zone flow involving goods held for trading or onward movement; confirm the organization’s customs procedure.
- Transhipment
- Movement of cargo through a zone/port en route to another destination.
- Break-bulk
- Cargo handled as individual packages or units rather than as one bulk mass.
- Re-export
- Export of goods previously imported or held in the zone, subject to the applicable filing and evidence.
Data sources and implementation status
- The FCZ UI uses trpc.fcz.breakBulk, entrepot, reexport, transhipment and tradingHouses procedures for list/detail/create/update/delete where implemented.
- Dedicated routers are mounted by backend/src/trpc/trpc.router.ts and implemented under backend/src/fcz/.
- Routes such as analytics, value-add and repackaging must be checked independently; the presence of an FCZ router does not prove each screen is persisted.
Permissions
- The API context can derive tenantId from a bearer token. Check the individual FCZ procedure for requireAuth/requireTenant; the shared CRUD helper does not enforce either guard itself.
- The repository defines global roles but no single FCZ role-to-operation matrix in these route pages.
- Only authorized operators/brokers should perform customs-controlled movement and declaration-related actions.
Troubleshooting
| Symptom | Check | Where to look |
|---|---|---|
| FCZ list is empty. | Check tenant selection and seed records for the matching FCZ resource; each resource uses its own router. | app/(app)/fcz/_components/FczRouteViews.tsx and backend/src/fcz/ |
| Detail lookup fails. | Use the selected record ID from the corresponding list; do not mix IDs between transhipment, entrepot and trading houses. | app/(app)/fcz/ |
| An analytics or value-add route has no live metrics. | Those routes are not proof of persisted FCZ API support; inspect the page’s composed component and router usage. | app/(app)/fcz/analytics/ and value-add/ |
Where things live
- FCZ page routes
- app/(app)/fcz/
- FCZ route queries and mutations
- app/(app)/fcz/_components/FczRouteViews.tsx
- FCZ backend routers
- backend/src/fcz/
- Router namespace registration
- backend/src/trpc/trpc.router.ts
Audience: operator · Last reviewed: