StaffGateway: information architecture

A1. The two portals

Both apps share one shell (header with language, notifications and user; light sidebar with expandable groups; theme switch), one sign-in flow, the StaffGateway design system, English and Arabic, light and dark.

A2. Admin portal sitemap

A3. Employee portal sitemap

A4. Modules, routes and sources

Each module is one script and one stylesheet, built from its slice of the Figma page. Screen counts are Figma frames, including every state and dialog.

Daily Attendance and Violations appear in the Figma side menu but have no screens anywhere in the file. They were designed from the attendance report screens and read the same records, so a person's day matches in every report; they need design review. A large "Dark" frame on the page is empty and was skipped; dark mode comes from the design system instead.

A5. Shared building blocks

• Organisation data: 4 clusters, 16 facilities and 240 generated people (English and Arabic names), shared by every module, so a person looks the same in roles, assignments, reports and the worklist.
• Shell: header (language, notifications, user), sidebar groups that open on the current page, drawer under 1024 px, full-screen sign-in pages, persona switch in the employee portal.
• Components (design-system tokens only): tables with sort and paging, filters, dialogs with discard prompt, side sheets, alert dialogs, toasts with Undo, tabs, switches, status badges with icon and word, stat cards, stepper, details list, timeline (audit trail and approvals), upload area, employee picker.
• Review links: every dialog and state opens from the URL (?dialog=…&state=…); the hub lists them all.
• Shared saved data: both apps read the same browser storage, so content and the theme set in the admin portal reach the employee portal (see A6).

A6. Key decisions per module

Each module records its full list at the top of its script. The ones that change behaviour or wording:

Admin portal → employee portal

• Announcements published in System management appear in the employee home News, in the order set on the Content Panel (hidden ones are left out), only for employees in the chosen audience (everyone, or their cluster). Drafts, scheduled and expired ones stay hidden. Their link opens from the details dialog.
• Web banners published there are the employee home hero, in the admin's order, with their uploaded image. No live banners → no hero.
• Theme: the effective theme (a scheduled one while it runs, else the default) recolours the whole employee portal through the brand tokens; its default appearance applies until the employee picks light or dark; an uploaded portal logo replaces the StaffGateway wordmark in the header. The admin portal keeps the StaffGateway look.
• An open employee-portal tab updates as soon as the admin saves; a reload applies the theme before the first paint.

The module answers three questions for a portal administrator: which roles exist, what each role may do (read-only), and who holds each role, where people can be assigned for a period or removed. Shift Admin goes one level further: each shift admin has a team of employees that can be edited.

1. Organisation and role model

Organisation hierarchy

Every scope in the module is expressed against this tree. Employees belong to a facility; a role assignment can carry a cluster or facility scope.

Roles

2. Sitemap and routes

The portal shell is shared: the header (logo, language switch, notifications, user), the sidebar (Home, Dashboard, Attendance System, Reports, Roles, System Management) and the theme switch. Only Roles is in scope here.

3. Screen inventory

4. Assign dialog by role

One dialog component, configured per role. The employee picker is the same everywhere; what changes is where the scope is asked and whether there is a second step.

Rules for every variant: the last step ends with Effective from (required, today by default, not in the past) and Until (optional, after the start). The main button is always enabled; pressing it with nothing selected shows the error under the picker and tints it. A required scope or date field shows its own error and takes focus. People who already hold the role are not offered again. An assignment that starts later counts as a holder and shows "Starts …"; one that has ended no longer counts.

5. Flows

F1 · Review what a role can do

flowchart LR
  A[Roles] -->|Roles permissions| B[Permissions: first role selected]
  B -->|pick another chip| B
  B -->|Back| A

F2 · Assign people to a role

flowchart TD
  A[Roles] -->|row action| B[Role users list]
  B -->|Assign user| C{Role needs filters first?}
  C -->|Manager, Shift Admin| C1[Pick cluster and facility]
  C -->|others| D[Pick employees]
  C1 --> D
  D -->|Add / Next with none picked| E[Error: select at least one employee]
  E --> D
  D -->|Cluster Admin, Cluster CEO| F[Pick cluster*]
  D -->|Facility Admin: Next| G[Pick cluster, then facilities]
  D -->|Shift Admin: Next| H[Pick the team]
  D -->|Org Head: Add| T[Effective from, until]
  F -->|Add| T
  G -->|Save| T
  H -->|Add| T
  T -->|start in the past or end before start| T
  T --> S[Saved: toast, list refreshed]
  D -->|Cancel or close with changes| X{Discard changes?}
  X -->|Continue editing| D
  X -->|Discard| B

F3 · Remove a role from a person

flowchart LR
  A[Role users list] -->|trash on a row| B{Remove role from user?}
  B -->|Cancel| A
  B -->|Remove role| C[Row removed, count updated, toast with Undo]

F5 · Replace a cluster's CEO

flowchart LR
  A[Cluster CEO users] -->|Assign user| B[Pick one employee]
  B --> C[Pick cluster]
  C -->|cluster has a CEO| D[Warning: this replaces NAME]
  C -->|no CEO yet| E[Add]
  D -->|Add| F[New CEO saved, old CEO loses the role, toast names both]
  E --> F

F6 · Change one facility admin's facilities

flowchart LR
  A[Facility Admin users] -->|pencil on a row| B[Edit facilities]
  B -->|Save with none| B
  B -->|Save| C[Row updated, toast]
  B -->|Cancel with changes| D{Discard changes?}

F4 · Edit a shift admin's team

flowchart LR
  A[Shift Admin users list] -->|Employees count| B[Person team]
  B -->|Add employees| C[Employee picker]
  C -->|Add| B
  B -->|trash on a row| D{Remove from team?}
  D -->|Delete| B

6. Permission matrix

C, R, U, D = create, read, update, delete. Read-only in the portal. Scope wording is normalised (for example "Within Cluster" and "Within Cluster Only" are one value).

7. Objects and fields

8. Messages and copy

9. Design system mapping

Brand data-brand="staffgateway", comfortable density, cards with border and a small shadow, underline tabs. No IT-RANKS endorsement anywhere.

Sidebar: light, with a blue pill for the current page, as in the StaffGateway employee app and the source Figma. The design-system server's StaffGateway setting was changed from brand (navy) to sidebar.style: "light" on 21 Oct 2026 to match (contrast 66/66, no color roles changed).

10. Decisions

The design left eight points open. Each has a recommended answer, and the build follows it. Recommended means it still needs the client's confirmation.