#Workspace chrome and navigation

Module id: MOD-SHELL
Doc profile: system

Shared authenticated chrome for TradeForce: the Header, contractor/company/admin SideBar menus, and the company SideMenuCompany reusable. After MOD-AUTH establishes a session, this module mounts the cabinet workspace and routes users into shift, time-tracking, payment, admin, and chat hosts via evidenced tab query params. Destination page bodies belong to later modules.

#Purpose

Signed-in contractors, companies, and admins need one consistent workspace frame—header actions plus a role-gated side menu—so they can reach My shifts, shift lists, time tracking, payments, company dashboard tabs, admin tabs, and chat without each product page reinventing chrome. This module owns layout composition, role menu visibility, header journeys (profile, logout, chat shortcut, notifications list + mark-read, presence, mobile drawers), and the navigation maps. It does not own shift lists, admin tables, chat threads, onboarding, or auth forms.

#Scope boundaries

#Actors

#Shell composition

Chrome is one cabinet workspace, not three apps. Host routes compose Header + SideBar (and SideMenuCompany where embedded) around a main outlet. Exactly one SideBar role region is visible from profiles.role. Mobile width toggles Header mobile_ and SideBar/SideMenuCompany mob_ custom states and the Header floating MENU group.

Composition and ChangePage chains are mapped under Traceability / IR evidence.

#Primary journeys

Journeys are reconstructed from Header and SideBar / SideMenuCompany workflows (ButtonClicked → ChangePage / ToggleElement / LogOut / MakeChangeCurrentUser / notification Search). Destination page bodies stay out of scope; this module only delivers chrome and the tab (or message) query contract.

#J1 — Enter authenticated workspace chrome

1. A signed-in user opens an authenticated host (/contractor/shifts, /contractor/time-tracking, /contractor/payments, /company/shifts, /admin, or /chat).
2. The app renders the cabinet shell with Header and SideBar; the main outlet stays empty or placeholder-only for destination modules.
3. SideBar shows exactly one role MENU: contractor, company, or admin, matching profiles.role.
4. At a narrow viewport, hamburger / mob controls toggle floating mobile chrome without breaking the outlet.
5. A signed-out visit to a host redirects to / and does not render workspace chrome.

#J2 — Header profile, logout, chat, notifications, and presence

1. User opens the profile drop and sees Edit profile and Log out.
2. Log out clears the session and navigates to /; Edit profile navigates by role (contractor → contractors tab on contractor shifts; company → profile tab on company shifts).
3. Message control opens chat with message=unapproved; time control opens contractor time-tracking with tab=time_tracking.
4. Notification bell: if the user has at least one recipient notification, the panel toggles and lists body text; unread rows are marked read for the current user. If count is zero, show “You don't have any notifications yet” and do not open the panel.
5. Online/Offline control updates profiles.is_online for the signed-in user.
6. On mobile Header MENU, company links Dashboard / Payments / Settings set the matching company tab values.

#J3 — Contractor sidebar navigation

1. Contractor sees MENU plus My shifts, Shifts, Time-tracking, and Payments.
2. My shifts → /contractor/shifts?tab=myshifts (nav myshifts).
3. Shifts → /contractor/shifts?tab=shiftlist (tabs shiftlist — preserve tabs vs nav difference).
4. Time-tracking → /contractor/time-tracking?tab=time_tracking.
5. Payments → /contractor/payments with no required tab.
6. Mobile contractor menu reaches the same four destinations.

#J4 — Company sidebar and SideMenuCompany navigation

1. Company user sees SideBar MENU with Dashboard, Company shifts, Reports, Payments, Contractors, Time-tracking, and Settings.
2. SideBar items navigate on /company/shifts with nav tab values; SideBar Settings uses tab=profile (not settings).
3. SideMenuCompany MENU shows Dashboard, Payments, and Settings → tab=dashboard|payments|settings respectively.
4. Mobile company menu duplicates evidenced SideBar destinations for company_shifts, contractors, time_tracking, and reports.
5. SideMenuCompany on the company dashboard remains hidden on load; do not invent an always-on second sidebar.

#J5 — Admin sidebar navigation

1. Admin sees MENU plus Shifts, Companies, Contractors, and Payments.
2. Shifts → /admin?tab=openshifts (admintab openshifts).
3. Companies → /admin?tab=companies (adminnav companies).
4. Contractors → /admin?tab=contractors.
5. Payments → /admin?tab=payments.
6. Mobile admin menu hits the same four tab targets; admin page bodies remain MOD-ADMIN.

#Navigation contracts

#Vertical slices (decompose)

#Side-effect contracts

#Shell-owned field mapping

Idiomatic target names for shell-owned persistence and chrome (source ids stay in Traceability / IR evidence):

#Style and fidelity

Provisional IR style mapping for chrome; shared tokens are owned here — SHELL-LAYOUT delivers the app-level stylesheet from IR styles (ir/slices/styles____part_all.json — 49 styles, 8 color tokens, 1 font token), and this cycle's module map has no separate design-system module. Stamp data-bubble-id on Header, SideBar, and SideMenuCompany roots and on migrated nav group roots used in parity checks. Breakpoints follow PageData around ≤1010px for floating mob chrome and Header G-main adaptation around ≤600px—do not invent a different grid. Transcribe MENU labels and header action copy exactly (Edit profile, Log out, empty-notifications toast).

#Failure modes

#Needs human clarification

None. After inventory + sanitized export chase for Header / SideBar / SideMenuCompany workflows, ChangePage tab/message params, notification Search + empty toast, presence writes, role visibility states, and the company-dashboard SideMenuCompany is_visible: false instance, shell behavior is encoded in the export. Destination bodies and notification create/email remain owned by other modules, not unanswered shell questions.

#Traceability

#IR evidence

#Module evidence roots

• bTHOe — Header (/element_definitions/bTHOf)
• bTHMl — SideBar (/element_definitions/bTHMm)
• bTMyh2 — SideMenuCompany (/element_definitions/bTNEP2)

Supporting segments: ir/slices/edef_bTHOf____root.json, ir/slices/edef_bTHMm____root.json, ir/slices/edef_bTNEP2____root.json, ir/slices/styles____part_all.json.

#Path-key ↔ inventory id aliases

#Chased navigation facts

• Contractor: myshifts (nav), shiftlist (tabs), time_tracking (tabs on time-tracking page), payments (no tab).
• Company SideBar: dashboard, company_shifts, reports, payments, contractors, time_tracking, profile for Settings label.
• SideMenuCompany: dashboard, payments, settings.
• Admin: openshifts (admintab), companies/contractors/payments (adminnav).
• Edit profile: contractor → contractors on contractor shifts; company → profile on company shifts.
• Chat shortcut: message = tabs unapproved.
• Empty bell copy: “You don't have any notifications yet”.
• Presence: offline_online_boolean true/false via MakeChangeCurrentUser on Online/Offline control.
• SideMenuCompany on company dashboard: is_visible: false (chased); only the reusable + hidden instance are evidenced—do not invent always-on dual nav.

#Role visibility

• Contractor menu visible when CurrentUser role equals contractor.
• Company menu when role equals company.
• Admin menu when role equals admin.

#Privacy & data

• Target RLS: authenticated users select notifications where they appear in recipient_ids; update only own membership in read_by_ids.
• profiles.is_online update is own-row only (AUTH profiles RLS).
• MOD-CHAT owns insert/send/email for notifications.

#Option sets used for shell routing

• nav: myshifts, dashboard, company_shifts, reports, payments, contractors, profile, settings, …
• tabs: shiftlist, time_tracking, unapproved, …
• adminnav: companies, contractors, payments, …
• admintab: openshifts, …
• role: contractor, company, admin.