Add a backoffice screen

Example used to test this page: GET /admin/items, an admin-only list of every item, and a /backoffice/items page that shows it in a table, with a link in the backoffice sidebar.

The backend guard is the security boundary. The frontend gates only decide who sees the page.

Backend steps

1. Add an admin controller to the feature's module, named admin-<feature>.controller.ts, the way backend/src/email/admin-email.controller.ts sits in the email module. Put the guards on the class, so a route added later inherits them:

   @ApiTags('admin-email')
   @ApiBearerAuth()
   @UseGuards(SessionGuard, AdminGuard)
   @Controller('admin/email')
   export class AdminEmailController {
   

   A list route uses parseOffset / clampLimit from src/common/pagination.ts and returns { items, total }, as AdminController.list in backend/src/admin/admin.controller.ts does.

2. Register it. Add the controller to the module's controllers and AdminModule to its imports, as backend/src/email/email.module.ts does:

   imports: [AuthModule, AdminModule],
   

3. State its policy in backend/src/common/route-auth.spec.ts. Add a POLICY entry keyed by the class name, for example AdminItemsController: { routes: { list: ADMIN } },. The spec finds every registered controller, so there is nothing to import.

   What fails if you skip it: "states a policy for every registered controller, and only those" fails and names the controller.

4. Add the path to ADMIN_ROUTES in backend/src/common/route-auth.http.spec.ts, for example ['GET', '/admin/items']. Nothing fails if you leave it out, but that spec makes real requests and checks an anonymous caller gets 401 and a signed-in non-admin gets 403, which proves the guard works and is not only declared.

5. Regenerate the contract and types (see step 8 of recipe 1).

Frontend steps

6. Create frontend/app/backoffice/<feature>/page.tsx. Copy app/backoffice/emails/page.tsx: a page component that renders a <Suspense> around an async component that fetches with serverApi(), styled with the shared ../ui.module.scss (styles.table, styles.tableWrap, styles.emptyRow, styles.error). Mutations go in a colocated actions.ts; see app/backoffice/users/actions.ts.

7. The gates are already there. frontend/proxy.ts returns a 404 for every /backoffice/* path unless the session belongs to an admin, and app/backoffice/layout.tsx checks again before rendering. A page under app/backoffice/ needs nothing extra. A page anywhere else is not gated, so keep admin screens under that folder.

8. Add the nav entry to the sidebar in frontend/app/backoffice/layout.tsx:

   <nav className={styles.sidebarNav}>
     <Link href="/backoffice/users">Users</Link>
   

   No test checks the link; the build only checks the page compiles.

9. Run ./verify.sh.

What the test run found

• The admin route, its POLICY entry and its ADMIN_ROUTES entry, the /backoffice/items page and the sidebar link: verify all green, and the build listed ƒ /backoffice/items.

Related

• Add the route auth policy
• Security Notes