Control center
Cargo walkthrough
Cargo is the general cargo-record surface with list, create, detail and analytics routes plus specialized bulk, FCZ, FIZ and hazmat views. In this route tree, persisted cargo queries and creation use cargo.main; the existence of other cargo routers does not mean these specialized pages are backed by them.
Key routes
- Cargo list
Browse tenant cargo records.
- New cargo
Create a cargo record using the cargo main mutation.
- Cargo analytics
Summarize the cargo records available to the page.
- Bulk cargo
Open bulk cargo handling views.
- Hazmat
Open hazardous-material cargo views.
Prerequisites and seed data
- Sign in with tenant context. Cargo API calls are made in the authenticated user’s tenant.
- Create cargo through the new-cargo form or seed cargo records in the tenant to populate list and analytics views.
- Have cargo reference and classification details ready before creating a record; specialized regulatory information must be verified in the relevant operational workflow.
Primary workflows
Create and review a cargo record
Create a tenant cargo record, then verify its persisted form in the list or detail route.
- Open the new-cargo form and enter the cargo record details. New cargo
- Return to the cargo list and confirm the record appears. Cargo list
- Select the record to open its detail page; the route reads the record by ID. Cargo list
Review specialized handling views
Use the specialized routes for the workflow context while remembering that this route tree persists through the main cargo router.
- Open the relevant bulk or hazmat view for operational context. Bulk cargo
- Use cargo analytics to review the records represented by the current data source. Cargo analytics
Concepts
- Cargo record
- The general cargo entity queried through cargo.main.list/byId and created through cargo.main.create in this route family.
- Bulk cargo
- Bulk cargo-specific presentation paths (dry, liquid, break-bulk, containerized); these routes must not be mistaken for separate persisted APIs unless wired.
- Hazmat
- A hazardous-material view and segregation route; regulatory classifications should be checked against authoritative data.
Data sources and implementation status
- Live UI data calls in this route family use trpc.cargo.main.list, trpc.cargo.main.byId and trpc.cargo.main.create.
- The backend also mounts cargo.bulk, cargo.fcz, cargo.fiz and cargo.hazmat routers, but these routes do not use those namespaces as their persistence source.
- The authoritative router registration is backend/src/trpc/trpc.router.ts; tenant scoping is supplied by the tRPC context and procedures.
Permissions
- The cargo UI expects an authenticated tenant session. The API context derives tenantId from the bearer token, but check whether a procedure applies requireAuth/requireTenant; shared CRUD handlers do not add those guards themselves.
- Global role values are defined in prisma/schema.prisma; no cargo-specific role mapping is established by the route UI.
- Treat dangerous-goods and customs decisions as controlled operational work; use approved role grants and authoritative classification records.
Troubleshooting
| Symptom | Check | Where to look |
|---|---|---|
| Cargo list is empty. | Verify tenant context and that a cargo.main record exists; the specialized route does not create the base record by itself. | app/(app)/cargo/_components/ and backend/src/cargo/cargo.router.ts |
| A specialized cargo screen looks populated but changes do not persist. | Confirm which mutation the screen calls; the known list/byId/create connection is cargo.main, not automatically cargo.bulk/fcz/fiz/hazmat. | app/(app)/cargo/ and backend/src/trpc/trpc.router.ts |
| Detail route cannot find a cargo item. | Open the row from the list and verify that its ID belongs to the active tenant. | app/(app)/cargo/[id]/page.tsx |
Where things live
- Cargo screens
- app/(app)/cargo/
- Cargo query and form surface
- app/(app)/cargo/_components/
- Cargo router namespace registration
- backend/src/trpc/trpc.router.ts
- Cargo backend procedures
- backend/src/cargo/
Audience: operator · Last reviewed: