Shell: Routing and layouts

Source: apps/oshun/admin/src/middleware.ts, apps/oshun/admin/src/app/error.tsx, apps/oshun/admin/src/app/loading.tsx, apps/oshun/admin/src/app/not-found.tsx, apps/oshun/admin/src/lib/session-cookie.ts

How the admin app handles routes, public paths, rate limiting, and the request-id stamp that flows from middleware into every page and audit entry.

Middleware composition#

apps/oshun/admin/src/middleware.ts runs on every request matched by:

/((?!_next/static|_next/image|favicon\.ico|.*\.(?:svg|png|jpg|jpeg|gif|webp|ico|woff|woff2|ttf|eot)$).*)

Order of operations:

1. Generate a requestId (timestamp + random suffix)
2. Resolve client IP (x-forwarded-for first hop, then x-real-ip, fallback 127.0.0.1)
3. Rate-limit check (production only): 120 requests / 60 s window / IP
4. Public-path check
5. Session-cookie check (for non-public paths)
6. Forward request with x-request-id header; attach X-Request-Id to response

Public paths#

const PUBLIC_PATHS = new Set<string>(['/unauthorized', '/handoff']);
const PUBLIC_PREFIXES = ['/_next', '/api', '/icons', '/images', '/favicon'];

• /unauthorized — auth-denial UI; takes reason and returnTo query params
• /handoff — privileged handoff from consumer to admin session
• /_next/*, /api/*, /icons/*, /images/*, /favicon* — never auth-gated

Any other path requires OSHUN_ADMIN_SESSION_COOKIE_NAME cookie that parses cleanly via parseAdminSessionToken. Missing or invalid → redirect to /unauthorized?reason=<missing-session|invalid-session>&returnTo=<original>; invalid token also cookies.delete(OSHUN_ADMIN_SESSION_COOKIE_NAME) on the response.

Rate limiting#

In-memory rateLimitMap keyed by IP.

• Threshold — 120 requests per 60 s
• Local dev exemption — process.env.NODE_ENV !== 'production' || hostname === 'localhost' || hostname === '127.0.0.1'
• Response when limited — 429 Too Many Requests with Retry-After: 60 and X-Request-Id header
• Window reset — first request after resetAt starts new window

In-memory store note: rate-limit state is per-instance. In multi-replica deploys, this is local to the replica. Open question worth flagging in ops.

Request ID#

Every request gets req_<timestamp>_<random8>. The ID flows three places:

• Stamped on the response (X-Request-Id header)
• Forwarded to the page via x-request-id request header (read with headers() in server components — see handoff/page.tsx line: hdrs.get('x-request-id'))
• Logged (verify telemetry pipeline)

Used for log correlation, audit trail joining, and on-screen support references.

Route groups#

The admin app does not use Next.js route groups — every segment is a real URL segment.

Catch-all routes#

None. Every route is explicit. Unknown paths → not-found.tsx (default Next 404 behavior).

Special files#

• app/error.tsx — segment-level error boundary; 'use client'; shows heading "Something broke inside the admin shell", body with error.digest, "Retry workspace" button calls reset()
• app/loading.tsx — global loading; <main role="main"> with aria-live="polite" "Loading operations cockpit…"; no skeleton
• app/not-found.tsx — workspace-not-found UI; h1 "Workspace not found"; link back to /; metadata.title = 'Workspace not found'
• No app/global-error.tsx — error.tsx is the only error UI

Sub-route patterns#

Some routes have a single child:

No parent index pages for /isis, /messaging, /tenant-console, /__test — only the named children. Direct visits to those parents hit not-found.tsx.

States#

• Anonymous on a gated path — middleware redirects to /unauthorized?reason=missing-session&returnTo=<path>
• Invalid session token — middleware deletes cookie and redirects to /unauthorized?reason=invalid-session&returnTo=<path>
• Rate limited — 429 page with Retry-After: 60 and the request ID
• Valid session — request continues to the page; x-request-id header propagates
• Public path (/unauthorized, /handoff) — no session check; page renders for anyone (with its own internal logic re: customer session for /handoff)
• 404 on unknown route — not-found.tsx; preserves admin shell chrome? No — global not-found.tsx; verify visually
• Error in page — error.tsx catches; "Retry workspace" button

Cross-references#

• 01-app-shell.md — AdminShell mounts inside each page after middleware passes
• 03-auth-session.md — the session cookie this middleware validates
• Session cookie module: apps/oshun/admin/src/lib/session-cookie.ts

Open questions / known gaps#

• Document the exact format of admin session tokens (the parseAdminSessionToken return shape lives in lib/session-cookie.ts)
• Confirm rate-limit storage strategy in production — in-memory per-replica is a known limitation
• Verify not-found.tsx doesn't leak the admin shell to unauthenticated visitors (it's not in PUBLIC_PATHS, so middleware should bounce them first)
• Document the x-request-id propagation — which BFF calls forward it for audit-trail joining?