Control center
Administration walkthrough
Administration contains tenant and user management, role reference surfaces, rule-pack routes, audit views, billing, and zone records. User and tenant pages use backend CRUD procedures; several other routes are UI surfaces whose persistence must be confirmed in their own implementation before relying on them.
Key routes
- Users
Browse users in the current tenant and open user creation or detail flows.
- Tenants
Browse tenant records and open tenant creation or detail flows.
- Roles
Inspect role-related administration surfaces.
- Audit log
Review the administration audit surface.
- Rule packs
Browse rule-pack records and open a selected record.
Prerequisites and seed data
- Sign in with an account attached to a tenant. tRPC derives the authenticated user and tenant from the bearer token.
- Tenant and user lists need persisted records to show rows; create a tenant or user only if the corresponding backend mutation is available to your account.
- The application defines SUPER_ADMIN, ADMIN, OPS_MANAGER, WAREHOUSE_STAFF, CUSTOMER, AGENT, and AUDITOR. The UI does not define a universal role-to-route matrix.
Primary workflows
Review and maintain users
Use the user list to inspect tenant users and the available create/detail controls.
Review tenant configuration
Inspect tenant records and their individual configuration surfaces.
- Open the tenant list and identify the intended tenant record. Tenants
- Create a tenant only when authorized and when the backend accepts the operation. New tenant
Trace administrative changes
Use the audit route when investigating administrative actions.
Concepts
- Tenant scope
- A tenant ID may be attached to API context; individual procedures must enforce authentication and tenant isolation.
- Global role
- The persisted user role is one of the GlobalRole enum values in the Prisma schema.
- Rule pack
- A configurable rule bundle represented by the rule-pack route family; verify persistence in the page/API before treating edits as saved.
Data sources and implementation status
- The route components use tRPC user.list/create/update/remove and tenant.list/byId/create/update/delete procedures.
- The admin audit component calls customAgents.audit.list; other admin routes do not all share a common data backend.
- The backend router is assembled in backend/src/trpc/trpc.router.ts; authenticated context and requireAuth/requireTenant/requireRole middleware are in backend/src/trpc.
Permissions
- The user list explicitly requires authentication and tenant context; user create/update/remove additionally require ADMIN or SUPER_ADMIN.
- Tenant routes use the generic createCrudRouter; that helper does not attach requireAuth, requireTenant, or requireRole itself. Do not assume the UI or tenant filter is an authorization boundary.
- Global roles are SUPER_ADMIN, ADMIN, OPS_MANAGER, WAREHOUSE_STAFF, CUSTOMER, AGENT, and AUDITOR. The schema lists these roles but does not itself assign a universal route matrix.
Troubleshooting
| Symptom | Check | Where to look |
|---|---|---|
| User or tenant list is empty. | Confirm the active account has tenant context and that records exist; user and tenant list procedures have different middleware. | backend/src/trpc/trpc.context.ts and app/(app)/admin/_components/ |
| A create/update/delete action is forbidden. | Check the procedure’s role middleware and the current GlobalRole; UI visibility is not authorization. | backend/src/trpc/trpc.middleware.ts and the matching backend router |
| A route shows a shell but no persisted data. | Some admin routes do not use the user/tenant CRUD procedures; check the page component and router before treating the surface as implemented. | app/(app)/admin/ |
Where things live
- User screens
- app/(app)/admin/users/
- Tenant screens
- app/(app)/admin/tenants/
- User tRPC router
- backend/src/user/user.router.ts
- Tenant tRPC router
- backend/src/tenant/tenant.router.ts
- Role definitions and tenant relation
- prisma/schema.prisma
Audience: admin · Last reviewed: