ProjectR Docs
Screen MapDashboard

Shell & navigation

Dashboard: every screen, state and flow in Shell & navigation.

16 screens and overlays, 40 states, 1 flows. Frames show a real screenshot where one was captured and a wireframe card where the state needs data or conditions a device run cannot produce.

Flows

Error paths

Step 1
Wireframe

This page hit an error

Error

Route crashed

Shows message or Something went wrong, plus Reference digest, logs to Sentry

Not reachable on a device: Needs a server error, crash, race or code change

Dashboard error card with Try again
Try again
Step 2
Wireframe

Global error

Error

Fatal error

Shows error message and digest

Not reachable on a device: Needs a server error, crash, race or code change

Global error page outside the dashboard

Branches and edge cases

Errorfrom step 1
Wireframe

This page hit an error

Edge

Overview overrides

overview/error.tsx replaces this card for that segment

Not reachable on a device: Needs a server error, crash, race or code change

Overview throws
Errorfrom step 1
404 Something's missing (Web)
Unknown URL
Edgefrom step 1
Wireframe

Auth guard

Edge

Suspended account passes

Guard checks auth only, never role or account status

Needs data: Needs specific backend rows, a role, or a submitted write on a disposable record

Suspended staff, live session
Errorfrom step 1
Wireframe

App error boundary

Error

Caught error

Reported to Sentry; Next.js internal errors are re-thrown

Not reachable on a device: Needs a server error, crash, race or code change

Root layout error caught
Flow diagram

Screens and states

Root redirect

Root redirect (Web)
Redirectroot-redirect

Root redirect

Sends the bare domain to the overview.

src/app/page.tsx:3

Entry

  • Bare domain

Exits

  • Redirect → /dashboard/overview

States · 1

Edge
Signed out bounce · AuthGuard then sends unauthenticated users to sign-insrc/components/auth/auth-guard.tsx:78

Dashboard index redirect

Dashboard index redirect (Web)
Redirectdashboard-index

Dashboard index redirect

Redirects /dashboard to the overview.

src/app/dashboard/page.tsx:9

Entry

  • 404 Back to Home

Exits

  • Redirect → /dashboard/overview

Auth guard

Auth guard (Web)
GateAuthGuard

Auth guard

Requires a session or stored token for all dashboard pages.

src/components/auth/auth-guard.tsx:43

Entry

  • Every /dashboard route

Exits

  • No session → /auth/sign-in?callbackUrl=

States · 4

Loading
Loading spinner · No local token and session still pendingsrc/components/auth/auth-guard.tsx:93
Gate
Redirecting to sign in · No session and no tokensrc/components/auth/auth-guard.tsx:105
Edge
Cached token renders shell · Shell shows immediately while session resolvessrc/components/auth/auth-guard.tsx:85
Edge
Suspended account passes · Guard checks auth only, never role or account statussrc/components/auth/auth-guard.tsx:43

Captured states

Auth guard, Redirecting to sign in (Web)
Redirecting to sign in

Protected route

Wireframe

Protected route

Needs data: Needs an under-privileged account to see the gate

GateProtectedRoute

Protected route

Client role gate per feature using the permission matrix.

src/components/auth/protected-route.tsx:50

Entry

  • Each page wraps its content

Exits

  • Fail → AccessDenied

States · 2

Loading
Role loading · Two skeleton bars while the role resolvessrc/components/auth/protected-route.tsx:61
Gate
Role too low · Renders AccessDenied; there is no middleware, so this is client onlysrc/components/auth/protected-route.tsx:83

Access Denied

Wireframe

Access Denied

Needs data: Needs an account with role apps or too low a role

ScreenAccessDenied

Access Denied

Standard no-permission card.

src/components/auth/access-denied.tsx:40

Entry

  • Any failed ProtectedRoute check

Exits

  • Go Back → previous page
  • Dashboard → /dashboard/overview

States · 4

Gate
No permission · Default text: You don't have permission to access this featuresrc/components/auth/access-denied.tsx:61
Edge
Role box · Shows Your role; Required role only when minRole is passed (no page does)src/components/auth/access-denied.tsx:73
Edge
Custom message · deniedMessage overrides the default textsrc/components/auth/access-denied.tsx:61
Edge
Dashboard button loops for apps · apps user is sent to overview, which denies againsrc/components/auth/access-denied.tsx:102

404 Something's missing

404 Something's missing (Web)
Screennot-found

404 Something's missing

Global not-found page.

src/app/not-found.tsx:7

Entry

  • Unknown URL

Exits

  • Go back → previous page
  • Back to Home → /dashboard

States · 1

Edge
Dynamic pages never reach it · No route calls notFound(); pages use inline not-found statessrc/app/not-found.tsx:7

Global error

Wireframe

Global error

Not reachable on a device: Needs an error in the root layout; code change

Screenglobal-error

Global error

Last-resort boundary replacing the whole document.

src/app/global-error.tsx

Entry

  • Error in root layout or unbounded segment

Exits

  • Button → /dashboard/overview

States · 1

Error
Fatal error · Shows error message and digestsrc/app/global-error.tsx:143

This page hit an error

Wireframe

This page hit an error

Not reachable on a device: Needs a route that throws; code change

Screendashboard-error

This page hit an error

Per-route crash boundary that keeps the shell mounted.

src/app/dashboard/error.tsx:15

Entry

  • Render error in any dashboard route

Exits

  • Try again → reset()

States · 2

Error
Route crashed · Shows message or Something went wrong, plus Reference digest, logs to Sentrysrc/app/dashboard/error.tsx:22
Edge
Overview overrides · overview/error.tsx replaces this card for that segmentsrc/app/dashboard/overview/error.tsx:19

App error boundary

Wireframe

App error boundary

Not reachable on a device: Needs an error in the root layout; code change

InlineErrorBoundary

App error boundary

Root boundary reporting to Sentry with a reset button.

src/components/error-boundary.tsx

Entry

  • Wraps the root layout

Exits

  • Reset → re-render

States · 1

Error
Caught error · Reported to Sentry; Next.js internal errors are re-thrownsrc/components/error-boundary.tsx:23

Dashboard shell

Dashboard shell (Web)
InlineDashboardShell

Dashboard shell

Sidebar, header and scroll area with Suspense skeleton.

src/components/layout/dashboard-shell.tsx:33

Entry

  • Dashboard layout

Exits

  • Sidebar and header navigation

States · 4

Loading
Suspense skeleton · 6 cards plus 2 panels while a page loadssrc/components/layout/dashboard-shell.tsx:43
Edge
Sidebar state from cookie · Open state read client-side from sidebar_state cookiesrc/components/layout/dashboard-shell.tsx:28
Empty
Empty sidebar · Role apps, or role still loading, shows no sectionssrc/hooks/use-permissions.ts:166
Edge
Cached role softens flash · Role snapshot avoids a blank sidebar on reloadsrc/lib/role-snapshot.ts
Sidebar (Web)
InlineAppSidebar

Sidebar

Role-filtered navigation, footer docs links and user card.

src/components/layout/app-sidebar.tsx

Entry

  • Every dashboard page

Exits

  • Item → route
  • Account Settings → /dashboard/profile
  • Sign out → /auth/sign-in
  • Signed out Sign in → /auth/sign-in

States · 4

Edge
Parent hidden · Parent with children is dropped when no child survives the filtersrc/lib/nav-filter.ts:33
Empty
Section hidden · Section with zero visible items is droppedsrc/components/layout/app-sidebar.tsx:155
Edge
Parent is link and trigger · Parent rows navigate and also collapsesrc/components/layout/app-sidebar.tsx:83
Edge
Signed-out card · Shows Not signed in and a Sign in linksrc/components/layout/app-sidebar.tsx:222

Header notification bell

Header notification bell (Web)
SheetNotificationBell

Header notification bell

Popover with the signed-in staff member's own inbox.

src/components/layout/notification-bell.tsx:46

Entry

  • Bell button in header

Exits

  • Row click → mark read, follow actionUrl
  • Mark all read
  • View all → /dashboard/notifications

States · 5

Loading
Loading · List loads only while the popover is opensrc/components/layout/notification-bell.tsx:58
Empty
No notifications yet · Inbox is emptysrc/components/layout/notification-bell.tsx:165
Edge
Unread badge · Count badge caps at 99+src/components/layout/notification-bell.tsx:112
Error
Mark read failed · Toast: Could not mark the notification as readsrc/components/layout/notification-bell.tsx:66
Error
Mark all failed · Toast on mark all read failuresrc/components/layout/notification-bell.tsx:86

Captured states

Header notification bell, Unread badge (Web)
Unread badge

Command palette

Command palette (Web)
ModalKBar

Command palette

Keyboard navigation to the sidebar items allowed for the role.

src/components/kbar/index.tsx

Entry

  • Header search input
  • kbar shortcut

Exits

  • Action → router.push(url)
  • External link → new tab

States · 1

Empty
Empty palette · apps user gets no actionssrc/components/kbar/index.tsx:29

Export dialog

Export dialog (Web)
DialogExportDialog

Export dialog

Choose CSV columns and export rows matching current filters.

src/components/ui/export-dialog.tsx

Entry

  • Export button on Orders, Sessions, Users, Support,

Exits

  • Select all / Clear all
  • Cancel
  • Export → CSV download

States · 7

Loading
Columns loading · Column list loads before choosingsrc/components/ui/export-dialog.tsx:206
Empty
No columns available · No columns available for this exportsrc/components/ui/export-dialog.tsx:206
Edge
Export disabled · Disabled with 0 columns or while exportingsrc/components/ui/export-dialog.tsx:249
Edge
Size limit reached · Message asks to clear columns or narrow filterssrc/components/ui/export-dialog.tsx:76
Success
Export done · Toast carries the row countsrc/components/ui/export-dialog.tsx:148
Error
Export failed · Failure toastsrc/components/ui/export-dialog.tsx:160
Gate
Disabled for dashboard role · Each Export button is wrapped in AdminOnlysrc/components/ui/role-gate.tsx:20

Confirmation dialog

Confirmation dialog (Web)
DialogConfirmationDialog

Confirmation dialog

Generic confirm used by Orders, Sessions, Notifications, Webhooks.

src/components/ui/confirmation-dialog.tsx

Entry

  • Destructive actions on several pages

Exits

  • Confirm → action
  • Cancel

States · 2

Loading
Confirm loading · Loading prop disables the confirm buttonsrc/components/ui/confirmation-dialog.tsx
Edge
Destructive variant · Red confirm for destructive actionssrc/components/ui/confirmation-dialog.tsx

AdminOnly control gate

Wireframe

AdminOnly control gate

Needs data: Needs a dashboard-role account to see the disabled control

InlineAdminOnly

AdminOnly control gate

Renders child disabled with a tooltip for low roles.

src/components/ui/role-gate.tsx:20

Entry

  • Export, templates, queue, webhooks, reports

Exits

  • None

States · 1

Gate
Disabled with tooltip · e.g. Exporting order data requires admin rolesrc/components/ui/role-gate.tsx:20

Sign-in & access

Dashboard: every screen, state and flow in Sign-in & access.

Overview

Dashboard: every screen, state and flow in Overview.

On this page

FlowsError pathsScreens and statesRoot redirectDashboard index redirectAuth guardProtected routeAccess Denied404 Something's missingGlobal errorThis page hit an errorApp error boundaryDashboard shellSidebarHeader notification bellCommand paletteExport dialogConfirmation dialogAdminOnly control gate