Skip to content

Admin portal - Layout

Purpose

Every admin portal screen sits in the same frame, so operators always know where they are and can reach any part of the portal in one click, on a desktop or on a phone during an incident.

Users and permissions

All operators see the same frame. Which navigation items each role sees is set by the permission matrix in Operator access and audit (LAY-08).

Requirements

ID Priority Requirement
LAY-01 Must Every screen after sign-in is shown inside one frame: a sidebar with the portal name and the main navigation, a header with the sidebar toggle and the current section name, and the screen content.
LAY-02 Must The sidebar lists the sections of the navigation in this order and grouping: Overview (Dashboard /), Operations (Tenants /tenants, Provisioning /provisioning, System health /system-health), Administration (Operators /operators, Roles & permissions /roles, SMTP settings /smtp-settings, Activity log /audit-log). Choosing an item opens that section, and the item of the current section is highlighted, also on nested paths such as /tenants/<id>. Operators without operators:manage or smtp:manage do not see those items.
LAY-03 Must On screens 768 px wide or more, the sidebar can be collapsed to icons with the header toggle or Ctrl+B (Cmd+B on macOS); a collapsed item shows its name as a tooltip. The choice is remembered in the browser for the next visit.
LAY-04 Must On screens narrower than 768 px, the sidebar is hidden and the header toggle opens it as a drawer; choosing an item closes the drawer.
LAY-05 Should The browser tab title is <section> - BizOS Admin.
LAY-06 Must An address that matches no screen shows "Page not found" inside the frame, with a link to the dashboard.
LAY-07 Must The header top-right shows a visible Sign out control. The sidebar footer shows the signed-in operator's name and role and links to My account.
LAY-08 Must Navigation items the operator's role cannot use are hidden (Operators is shown to Owners only). The server still enforces every permission (ACC-04).
LAY-09 Should A "Change theme" button at the right of the header opens a menu to choose the theme (Twitter, AstroVista) and the colour mode (Light, Dark, System). The change applies at once, System follows the device setting, and the choice is remembered in the browser for the next visit. One choice applies to both the admin portal and the customer portal. Default: AstroVista, Dark. Dynamic transitions and micro-animations accompany route changes, cards, buttons, and dialogs.

Screens

Frame. Left sidebar: portal name at the top (links to the dashboard), then the navigation groups; footer shows the operator name/role and My account. Header across the content area: sidebar toggle and current section name on the left; theme menu, operator name, and Sign out on the right. Content below the header.

Section not built yet. Until a section's feature is built, its route shows the section name, a one-line description, and "This screen is not built yet."

Page not found. Heading "Page not found", one line of explanation, and a "Go to dashboard" button.

Business rules

  • The sign-in, MFA, and invite screens (Operator access and audit) are shown without the frame.
  • Section routes accept nested paths, so a feature can add sub-pages (for example tenant detail tabs) without changing the frame.

Acceptance criteria

  • LAY-01: Given any section, when it opens, then the main navigation, the sidebar toggle, and the section heading are on the screen.
  • LAY-02: Given /tenants/42, then the sidebar lists the six sections in the order above and only Tenants is marked as the current page; choosing Provisioning opens Provisioning.
  • LAY-03: Given a wide screen, when the operator collapses the sidebar and reloads the portal, then the sidebar is still collapsed.
  • LAY-04: Given a narrow screen, when the operator opens the drawer and chooses Tenants, then the drawer closes and Tenants is shown.
  • LAY-05: Given /audit-log, then the tab title is "Activity log - BizOS Admin".
  • LAY-06: Given an unknown address, then "Page not found" is shown with the navigation, and "Go to dashboard" opens the dashboard.
  • LAY-07: Given a signed-in Support operator, then the header shows Sign out at the top right, and the sidebar footer shows their name, the role Support, and My account.
  • LAY-08: Given a signed-in Operator or Support operator, then the sidebar has no Operators item.
  • LAY-09: Given any section, when the operator chooses AstroVista and Dark in the theme menu and reloads the portal, then the portal is shown in AstroVista dark and the menu shows both choices selected.
  • LAY-09: When the operator chooses Twitter and Light, then <html> is data-theme="twitter" without the dark class so Twitter light tokens apply.

Not yet implemented

Out of scope

  • Global search and notifications in the header.
  • Saving the theme choice to the operator's account (it is per browser).
  • The tenant workspace layout (web app).

Open questions

  1. Should the header show a breadcrumb trail (for example Tenants / Acme / Backups) once tenant detail exists, or is the section name enough?