Skip to content
GitHub

Dashboard and workspace

After sign-in the first page is the dashboard: a set of cards (Waiting on me, My requests, Quick start, Shortcuts, Messages for me, Announcement, Needs your attention, Service status, Sign-ins over the last 14 days). Each person chooses which to show, in what order and how wide; the layout is stored on the server, so signing in on another computer brings back the same one, and cards someone has no permission for never appear. Around the dashboard the interface has a few shared tools: the ⌘K command palette, keyboard shortcuts, a product tour, appearance settings in Profile, column visibility and order on lists, a per-user time zone and language, and a refresh prompt when a new version is deployed. Tabs are covered separately in Multi-tab.

Dashboard
WhatWhereStored
Dashboard and the Custom buttonDashboard /dashboard, every signed-in userServer, per user (all devices)
Command palette⌘K / Ctrl+K on any page—
Keyboard shortcutsPress ?, or Help in the top bar—
Product tourOpen from Help → Product tour or the command palette; never starts on its ownNot stored
Appearance and layout preferencesProfile → Theme / Layout / TabsBrowser
Display time zoneProfile → ProfileServer, per user
LanguageUser menu at top right → Language; also on the sign-in pageBrowser
List ColumnsAt the right of each list’s headerURL
CardContentWho sees itDefault
Waiting on meUp to 6 items, tabs All / To approve / Returned to me / DraftPeople with the approval center in their sidebar2/3 width, shown
My requestsProgress bars for the last 3 requests; Remind after a day without movementsame1/3, shown
Quick start4 workflows you can startsame1/3, shown
ShortcutsPages picked from your own sidebar, 6 by default, up to 12everyone1/3, shown
Messages for me4 unread messages, the same data as the belleveryone1/3, shown
Announcement5 noticeseveryonefull width, hidden by default
Needs your attentionAuto-disabled webhooks, failed jobs in the last 24 hours, an unusual rise in failed sign-ins todayAnyone with open:webhook:list, task:scheduler:edit or log:login:list1/2, shown
Service statusAPI / database / cache / scheduler / worker, plus online sessions per clientSuperusers1/2, shown
Sign-ins, last 14 daysDaily bars of successful / failed sign-inslog:login:listfull width, shown

Cards without permission are not rendered, rather than rendered as an empty “no access” shell, and the backend endpoints behind them check the same conditions. The “System” group appears only for people who can see at least one of its cards.

Click Custom at the top right to enter edit mode (the URL gains edit=true, which survives a reload):

  • Show or hide each card
  • Drag to reorder, or use the keyboard (space to pick up, arrow keys to move, space to drop); each group is ordered separately
  • Four widths: 1/3, 1/2, 2/3, Full
  • Choose which pages go in Shortcuts
  • Restore defaults

The layout is stored per user on the server (table sys_user_preference, key dashboard.layout), the same in any browser on any computer. Compatibility rules keep upgrades from breaking it: unknown cards are ignored, new cards are appended at the end, and one bad field falls back for that field only; a layout that cannot be read at all shows a warning and the default layout. If loading the layout fails, an error is shown with the default layout and editing is disabled (otherwise saving would overwrite the real layout on the server); if saving fails, the error stays in the editor and the draft is kept.

Press ⌘K (Ctrl+K on Windows / Linux) to open the command palette. It searches three kinds of things:

  • Open tabs
  • Pages: pages in your own sidebar (ones already open are not repeated), external links included
  • Actions: Reload this page, Close other tabs, Close all tabs, Keyboard shortcuts, Product tour; actions that cannot run right now are not listed

Matching is in order (the typed characters appear in order in the name, path or hint), with name matches ranked first. The palette does not search business data and has no “recent” list.

Shortcuts:

KeysAction
⌘K / Ctrl+KOpen the command palette
⌘B / Ctrl+BCollapse / expand the sidebar
?Keyboard shortcuts (not triggered while typing in an input)
↑ ↓ · Enter · EscChoose, open, close in the palette
Middle-click a tabClose it (can be turned off in preferences)
Right-click a tabTab menu

A seven-step tour: sidebar → tabs → page content → command palette → notifications → profile → help. It never starts on its own; open it from Help → Product tour in the top bar or the command palette. People who turned tabs off skip that step automatically. A notice that pops up while the tour is open waits until the tour ends.

In the Theme, Layout and Tabs sections of Profile; changes apply immediately and there is no save button:

SettingDefaultOptions
Theme modeLightLight / Dark / System
Accent colorIndigo7 colors
Corner radiusSoft6 levels
Interface densityStandard5 levels (24–36 px controls)
Scroll behaviorContent areaContent area (top bar and tab bar stay put) / Whole page
Show tab barOn
Tab appearanceCardButton / Card / Soft / Underline
Tab icons · middle-click to close · drag to reorderOn

These are stored in the browser (admin:prefs in localStorage) and do not follow the account: another browser starts from the defaults. Restore defaults resets all of them. The sign-in page follows the theme too, and has its own theme and language switches.

  • Columns: the Columns button at the right of the header lets you tick which columns show and drag to reorder them. The choice goes into the URL (hide= for hidden columns, cols= for an order that differs from the default), so it survives a reload and a shared link shows the same columns; Restore defaults removes both parameters.
  • Pagination: 10 / 20 / 30 / 50 rows, 20 by default; written to the URL only once changed.
  • Filter bar: press Enter to search; when conditions have changed but not been applied, a line says “Filters changed — press Enter to apply”, and input is validated before searching; conditions can be added and the bar collapsed. Conditions go into the URL and Reset clears them. Saved views (named sets of conditions) are stored only in the browser, and the UI says so.
  • Time zone is per person, set under Profile → Profile, default Asia/Shanghai. It only changes how times are displayed (lists, details, the dashboard greeting and where “today” starts, times in exported files); it does not change when logs were recorded or which time zone scheduled jobs run in. After changing it, tabs that are already open convert times once their data is refreshed.
  • Language is Simplified Chinese or English, switched from the user menu or the sign-in page and stored in the browser; requests then carry Accept-Language, so backend messages, config names, endpoint descriptions and the like switch language too. Business data entered by users is not translated.

How do people find out about a new version?

Section titled “How do people find out about a new version?”

Every 10 minutes, and whenever the browser tab regains focus (at most once a minute), the frontend fetches /version.json and compares it with the version it was built with; it also catches the “failed to load page code” errors that only happen after a deploy. When a new version is found, a toast that stays until dismissed says “A new version is available” with a Refresh button. It never reloads by itself: the user may be in the middle of a form.

  1. Add an entry to dashboard/cards/registry.ts: id, group, title, available (who sees it), default width, default visibility.
  2. Write the component under cards/, wrapped in DashboardCard.
  3. Make available match the permission check of the endpoint it reads, one endpoint per card; otherwise the card shows and the request gets a 403.
  4. Add strings to both locale files.
  5. Never change a card’s id: saved layouts identify cards by it, so a rename means one card removed and a new one added.

Adding a command palette action: add it to actionItems in shell/command-menu.tsx; new pages appear automatically once they have a menu row. Adding a shortcut has no registry: add your own listener, call preventDefault for modifier combinations, check that single keys are not typed into an input, and add a line to shortcuts-dialog.tsx. Adding a tour step: add the step in shell/tour/shell-tour.ts, put data-tour on the target element (pnpm arch:check fails if the target does not exist).

  • Appearance preferences, language and saved views live only in the current browser and are not synced with the account; only the dashboard layout and the time zone are stored on the server.
  • There is only the one shell tour; per-page tours do not exist yet.
  • The command palette does not match pinyin initials.
  • Changing the time zone does not convert already-open tabs until their data is refreshed.
  • Quick ranges like “today” in the filter bar use the browser’s local time, while the dashboard’s “today” uses the display time zone; when the two differ, a details link from the dashboard may be off by a day (inferred from the code, not covered by a test).
  • Unit tests (Vitest): dashboard/layout.test.ts (17 tests: new cards go last, an unreadable layout falls back to the default and is flagged, …), card-rules.test.ts, and the filter bar’s params.test.ts (38 tests).
  • Backend: test_user_preference.py (an unsaved key reads as null, not 404; only your own preferences), test_dashboard_ops.py (visit stats cut days in the viewer’s time zone).
  • In the browser (Playwright): dashboard-personalize.spec.ts (10 tests, including the same person in a second browser seeing the same layout, and a failed layout load showing an error with editing disabled), command-palette.spec.ts (? opens shortcuts, but typing a question mark in an input does not), tour.spec.ts, new-version.spec.ts, query-bar.spec.ts.
  • No E2E yet for appearance preferences, switching time zone, or column visibility.

On the live demo (admin / 123456), click Custom on the dashboard, turn on Announcement, drag it to the top, make it 1/2 wide and save; sign in again from a private window and you get the same layout. Press ⌘K and type “用户” to jump to Users (menu titles are in Chinese on the demo); press ? for all shortcuts. Everyone on the demo shares admin, including the dashboard layout, so please Restore defaults afterwards.