Control center
Search walkthrough
Search provides a workspace for locating cargo and trade declaration records. The current screen searches the existing cargo.main and tradeOps.declarations list APIs; it is not a global full-text search across every domain.
Key routes
- Search workspace
Search the connected cargo and declaration data sets.
- Cargo
Open cargo records after locating a match.
- Declarations
Open the trade declaration list.
- Order management
Continue operational investigation in order routes.
Prerequisites and seed data
- Sign in with access to the tenant containing the records.
- Cargo and declaration records must already exist; search only returns data available to the connected list APIs.
- Use meaningful references or description terms supported by the current search workspace.
Primary workflows
Find a cargo or declaration
Search the connected record types and continue from the appropriate domain list.
- Open the search workspace and enter a reference or supported text term. Search workspace
- Open the cargo route when the result is a cargo record. Cargo
- Open the declarations route when the result is a customs declaration. Declarations
Investigate a missing result
Check whether the record exists in the actual source list before concluding that search failed.
- Check the cargo list for the reference. Cargo
- Check the declaration list for the reference. Declarations
- Return to search and retry using the exact reference. Search workspace
Concepts
- Search scope
- The current implementation searches the cargo and declaration list results, not every application table.
- Tenant scope
- The tRPC context may contain a tenant ID; the source procedures must apply the intended tenant filter and guards.
- Reference
- An operational identifier that can help locate a cargo or declaration record.
Data sources and implementation status
- SearchWorkspace queries trpc.cargo.main.list and trpc.tradeOps.declarations.list, with a bounded result request.
- There is no global search endpoint used by this page; records outside those two sources are not covered.
- tRPC routers are registered in backend/src/trpc/trpc.router.ts and are tenant-aware through the request context.
Permissions
- The search screen queries cargo and declaration procedures; the API context may derive tenantId from a bearer token, but the shared CRUD helper does not itself require authentication or non-null tenant context.
- The screen does not create additional access control. Confirm the specific source procedures apply the intended tenant and role guards.
- GlobalRole values are defined in prisma/schema.prisma; there is no separate search role in the route.
Troubleshooting
| Symptom | Check | Where to look |
|---|---|---|
| A record cannot be found. | Confirm it exists in the cargo or declaration source list, belongs to the active tenant, and falls within the list query limit. | app/(app)/search/SearchWorkspace.tsx |
| Results from other domains are absent. | The current page is not global search; only cargo.main and tradeOps.declarations are queried. | app/(app)/search/SearchWorkspace.tsx |
| One category returns an API error. | Check the corresponding source router and tenant authorization independently. | backend/src/cargo/cargo.router.ts and backend/src/trade-ops/declarations/ |
Where things live
- Search route
- app/(app)/search/page.tsx
- Search query implementation
- app/(app)/search/SearchWorkspace.tsx
- Cargo source API
- backend/src/cargo/cargo.router.ts
- Declaration source API
- backend/src/trade-ops/declarations/
- Router registration
- backend/src/trpc/trpc.router.ts
Audience: mixed · Last reviewed: