UI Layout and Navigation¶

Status: Specified · Scope: All modules

Defines the application shell, navigation model, route structure, role-differentiated visibility, settings area, alert surfacing, and mobile behaviour. All module UIs are built within this shell.

⊞ Dashboard

Projects

▶Canary Wharf Ph.2

📓 Site Diary

👷 Personnel

📋 Attendance

🚜 Plant & Equipment

⚠️ Incidents

📄 Documents

📦 Deliveries

🤝 Subcontractors

▶Kings Cross Station

📓 Site Diary

👷 Personnel

📋 Attendance

🚜 Plant & Equipment

⚠️ Incidents

📄 Documents

📦 Deliveries

🤝 Subcontractors

⚙ Settings

3 expiring this week 2 CSCS cards · 1 LOLER inspection (Site A crane) View all →

RIDDOR deadline in 2 days Canary Wharf Ph.2 — INC-004 must be reported to HSE View →

4

Active Sites

2

Open Incidents

3

Expiring This Week

47

Workers On Site Today

Projects

Canary Wharf Phase 2PRJ-001

2

Sites

31

On site today

1

Open incidents

2 expiringRIDDOR due

Kings Cross StationPRJ-002

2

Sites

16

On site today

1

Open incidents

1 expiringNo overdue items

Recent Activity

📓

Site diary entry added — Canary Wharf Ph.2, Site A

James Fletcher · 10 minutes ago

👷

New worker added — Marcus Obi (Steel Fixer)

Sarah Nwosu · 42 minutes ago

⚠️

Near miss reported — Kings Cross, Platform 9 works

Dan Pearce · 1 hour ago

App Shell¶

Three fixed regions. All module content renders in the main content area.

┌─────────────────────────────────────────────────────────┐
│  Top bar                                                │  48px fixed
├───────────────┬─────────────────────────────────────────┤
│               │                                         │
│   Sidebar     │   Main content area                     │
│   240px       │   flex-1, scrollable                    │
│   fixed       │                                         │
│               │                                         │
└───────────────┴─────────────────────────────────────────┘

Top bar¶

Zone	Left	Centre	Right
Content	Tenant logo (white-label)	—	Notification bell · User avatar + dropdown

Tenant logo — renders the tenant's uploaded logo; falls back to the Construo wordmark. Clicking it navigates to /dashboard.
Notification bell — shows unread count badge. Opens a dropdown of the 10 most recent notifications, each linking directly to the relevant entity. "View all" link goes to /notifications.
User avatar dropdown — name, role label, "My preferences", "Sign out".

Fixed at 240px. Collapses to icon-only (48px) at ≤1024px breakpoint via a toggle. On mobile (≤768px) collapses entirely behind a hamburger menu in the top bar.

Structure:

[Tenant name / logo mark]
────────────────────────
  Dashboard

  Projects
  ▾ Canary Wharf Phase 2        ← expanded
      Site Diary
      Personnel
      Attendance
      Plant & Equipment
      Incidents
      Documents
      Deliveries
      Subcontractors
  ▸ Kings Cross Station         ← collapsed
  ▸ A1 Upgrade — Stevenage

  + New Project                 ← Project Manager and above only

────────────────────────
  Settings                      ← Tenant Admin only

────────────────────────
[Avatar]  Gari Smith
          Technical Architect

Project expansion behaviour: - Clicking a collapsed project expands it in-place, revealing its module list. - Multiple projects can be expanded simultaneously. - The active route highlights the current module item. - The module list shown reflects the tenant's enabled modules — disabled modules are hidden, not greyed out.

Main content area¶

Full height, scrollable. Contains:

Page header — page title, breadcrumb, primary action button (e.g. "New diary entry").
Alert strip — appears only when there are active alerts for the current context (see Alert Surfacing).
Page content — module-specific.

Dashboard (default landing)¶

Route: /dashboard

Cross-project view. Content is scoped to what the authenticated user can see based on their role and project access. Project access is not embedded in the JWT — the API checks it live (Redis-cached) on every request. The React app queries the project list and receives only the projects the user can access; it does not read or decode JWT claims for authorisation.

Page sections:

Alert strip — priority-ordered list of all items requiring action (see Alert Surfacing).
Summary tiles — four stat tiles: Active Sites · Open Incidents · Expiring This Week · Workers on Site Today. Values are aggregated across all accessible projects.
Project cards — one card per accessible project showing: project name, site count, active headcount, open incident count, and any overdue items. Clicking a card expands the project in the sidebar and navigates to the project overview.
Recent activity feed — chronological list of recent entries across modules (diary entries, incidents raised, new personnel added). Scoped to the user's accessible projects.

Project overview¶

Route: /projects/:projectId

Summary view for a single project.

Site list with status and today's headcount per site
Open incidents
Items requiring attention (expiries, overdue inspections) scoped to this project

Module pages¶

Route: /projects/:projectId/[module] for project-level modules. Route: /projects/:projectId/sites/:siteId/[module] for site-level modules.

See individual module specs for page structure.

Route Structure¶

/                                               → redirect → /dashboard
/dashboard                                      → cross-project dashboard

/projects                                       → project list (fallback if no projects)
/projects/new                                   → create project form
/projects/:projectId                            → project overview
/projects/:projectId/edit                       → edit project

/projects/:projectId/sites/:siteId              → site overview
/projects/:projectId/sites/:siteId/diary        → site diary
/projects/:projectId/sites/:siteId/attendance   → attendance / sign-in
/projects/:projectId/sites/:siteId/plant        → plant & equipment
/projects/:projectId/sites/:siteId/incidents    → incidents & near misses
/projects/:projectId/sites/:siteId/deliveries   → deliveries

/projects/:projectId/personnel                  → personnel (project-level)
/projects/:projectId/documents                  → document register
/projects/:projectId/subcontractors             → subcontractors
/projects/:projectId/inductions                 → induction management

/notifications                                  → full notification history

/settings                                       → settings landing  [Tenant Admin]
/settings/users                                 → user management
/settings/modules                               → module enable/disable
/settings/fields                                → field schema builder
/settings/notifications                         → notification configuration
/settings/branding                              → logo, colours, white-label

/profile                                        → user preferences, SMS opt-in/out

All routes under /settings redirect to /dashboard for non-admin roles. The Settings nav item is hidden entirely for non-admin roles — the redirect is a defence in depth measure.

Settings Area¶

Accessible only to Tenant Admin and Platform Admin roles. Reached via the "Settings" item at the bottom of the sidebar.

Settings has its own sub-navigation (left rail within the main content area):

Section	Purpose
Users	Invite users, assign roles, deactivate accounts
Modules	Enable or disable platform modules for this tenant
Fields	Field schema builder — add custom fields to any entity
Notifications	Configure event types: enabled, channels, recipients, thresholds
Branding	Upload logo, set primary colour, configure email from-name

Settings pages do not have a project context — they are tenant-wide.

Role-Differentiated Visibility¶

What each role sees¶

Area	Platform Admin	Tenant Admin	Project Manager	Site Manager	Site Operative	Viewer
Dashboard	All tenants	All projects	Assigned projects	Assigned sites	Own sites	Assigned projects
Project list	All	All	Assigned	Assigned	Assigned	Assigned
Module pages	All	All	Full CRUD	Create/edit on assigned sites	Own entries only	Read-only
Settings	—	Full access	Hidden	Hidden	Hidden	Hidden
New Project button	—	✅	✅	Hidden	Hidden	Hidden
New Site button	—	✅	✅	Hidden	Hidden	Hidden

UI treatment of restricted actions¶

Hidden — element does not appear in the DOM. Used for entire nav sections and primary action buttons a role can never access.
Disabled — element is visible but non-interactive, with a tooltip explaining why. Used sparingly, only where awareness that the action exists is useful (e.g. a Site Manager seeing a greyed-out "Export PDF" that requires Project Manager role).
Read-only form — inputs render as static text. Used for Viewer role on all entity detail pages.

The API is always the authoritative enforcement point. UI visibility is UX only.

Alert Surfacing¶

Alerts appear in two places:

1. Notification bell (top bar)¶

Badge shows count of unread notifications.
Dropdown lists the 10 most recent, newest first.
Each item shows: event type icon · description · entity name · time ago.
Clicking an item marks it read and navigates to the entity.
"Mark all read" action at the top of the dropdown.
"View all" navigates to /notifications.

2. Alert strip (dashboard and module pages)¶

The alert strip appears at the top of the main content area whenever there are active unresolved alerts in scope.

On the dashboard — shows all alerts across all accessible projects, grouped by severity:

🔴  2 overdue items          LOLER cert expired (Site A crane) · RIDDOR deadline missed
🟡  5 due this week          3 licences expiring · 1 plant inspection · 1 document

Clicking a grouped alert expands it to show individual items, each linking to the entity.

On a module page — shows only alerts relevant to that module and project/site context. For example, on the Plant & Equipment page for Site A, the strip shows only plant-related alerts for Site A.

Severity colours:

Colour	Meaning
🔴 Red	Overdue or expired — action required now
🟡 Amber	Due within the configured threshold — action required soon
🔵 Blue	Informational — e.g. induction blocked sign-in (resolved when induction completes)

Mobile Responsive Behaviour¶

Breakpoints:

Breakpoint	Behaviour
≥1280px	Full layout — sidebar expanded at 240px
1024px–1279px	Sidebar collapses to icon-only (48px)
≤768px	Sidebar hidden; hamburger menu in top bar opens a full-height overlay nav

Mobile-specific layout rules:

Tables — render as stacked cards on ≤768px. Each row becomes a card with label + value pairs. Sort and filter controls move to a slide-up drawer.
Forms — single column. Full-width inputs.
Page header — title and primary action button stack vertically if the title is long.
Alert strip — shows only the highest-severity alert; tap to expand all.
Module pages — no layout changes beyond the above. All modules are accessible on mobile.

High-frequency on-site flows (sign-in, diary entry, plant log, incident report) are tested on real devices in Sprint 18 and given priority treatment for touch targets and thumb reach.

Component Conventions¶

All UI is built with shadcn/ui components and Tailwind CSS utility classes. The following conventions apply across all module UIs:

Pattern	Implementation
Data tables	TanStack Table v8 with shadcn `Table`. Sortable columns, column visibility toggle, CSV export.
Forms	React Hook Form + Zod. Inline field-level errors. Submit disabled until form is valid.
Modals / sheets	shadcn `Dialog` for confirmations and small forms. `Sheet` (slide-in panel) for larger create/edit forms.
Empty states	Centred illustration + heading + primary action button. Every list page must have an empty state.
Loading states	Skeleton loaders (shadcn `Skeleton`) for initial page load. Spinner on form submission buttons.
Confirmation dialogs	shadcn `AlertDialog` for destructive actions. Never use browser `confirm()`.
Toasts	shadcn `Sonner` for success/error feedback after mutations. Position: bottom-right.
Custom fields	Rendered dynamically from `field_definitions`. Field type determines component: text → `Input`, select → `Select`, date → `DatePicker`, boolean → `Switch`, file → `FileUpload`.