Unified workspace: one tools shell across selected instances

Objective

• Let office staff (and similar internal roles) with memberships in multiple Attik instances work in one tools shell instead of switching company and reloading for every task.
• Support a user-defined workspace: a home instance for branding/navigation plus a selected set of included instances where the user’s permissioned reads (and eventually writes) are available in one place.
• Reduce coordinator friction for multi-brand operations (e.g. Florida / Monument-style groups) while preserving per-instance data isolation and permission boundaries.

Background

• Today every tools session has a single active company (selectedCompany on the auth session, updated via POST /auth/web/switch-company in webAuthEndpoints.ts).
• Switching company in the UI calls switchCompanyAction and triggers a full page reload (NavUser.tsx).
• Nearly all tools APIs scope data with res.locals.company._id (calendar, schedule, quotes, inspections, events). Cross-company behavior exists only in narrow admin paths (e.g. cc-dashboard with getAllowedCompanyIds, GET /company/my-companies, Client Care Dashboard).
• The same user can hold multiple memberships (membershipSchema.ts) with different roles and permissions per _companyId; copyMembershipToCompanies.ts provisions separate employee records per company but does not unify the tools experience.
• This epic is separate from ATT-1714 (cross-instance inspector calendar blocking) and ATT-1763 (cross-instance quote handoff from workorder). Those solve scheduling availability and job→quote transfer; this epic solves coordinator UX and federated access across instances.

Child issues

Implement in dependency order via blockedBy:

1. (created below) — Workspace model + session extension
2. (created below) — Workspace configuration UI (Admin and/or account settings)
3. (created below) — Cross-company authorization helpers
4. (created below) — Federated calendar view
5. (created below) — Federated worklist / tasks / inspections lists
6. (created below) — Navigation shell without full reload on context change
7. (created below) — Write paths and explicit create targeting

Product decisions (proposed — confirm during implementation)

• Audience (v1): Office staff / coordinators with multiple active memberships; decision needed whether inspector tools roles are in scope.
• Workspace: homeCompanyId + includedCompanyIds[] ⊆ user’s active memberships.
• Permissions: Check against the resource’s _companyId membership (not a naive union of all permissions).
• Creates (v1): Always target one _companyId (explicit picker or row context); no ambiguous cross-company writes.
• Phasing: Prefer read federated first (calendar + high-traffic lists), then expand writes.
• Security: Optional client companyIds must always be intersected with allowed memberships (pattern from ccDashboard.ts).

Scope (epic-level)

Coordinates session, authorization, federated APIs, and tools UI. Detail lives on child issues. Key touchpoints:

• Session / switch: attik-backend/src/util/functions/betterAuth/web/webAuthEndpoints.ts, attik-frontend/src/actions/switchCompany.ts
• Memberships: attik-backend/src/models/membershipSchema.ts, attik-frontend/src/components/navbar/NavUser.tsx
• Multi-company precedent: attik-backend/src/routes/ccDashboard.ts, attik-backend/src/routes/company.ts (/my-companies), attik-frontend/src/app/admin/client-care-dashboard/
• Calendar: attik-frontend/src/app/tools/calendar/MasterCalendar.tsx, attik-backend/src/routes/calendar.ts, attik-backend/src/routes/schedule.ts

Out of scope: Merging tenant data; replacing instance-management; implementing ATT-1714 or ATT-1763 (integrate when those ship).

References

• Related: ATT-1714 — Cross-instance shared calendars
• Related: ATT-1763 — Create quote in another instance from existing job

Diagram

flowchart TB
  subgraph today [Today]
    S[Session selectedCompany]
    T[Tools UI single company]
    API[APIs filter res.locals.company]
    S --> T --> API
  end
  subgraph target [Unified workspace]
    W[Workspace home + included companies]
    F[Federated read APIs]
    UI[One shell with company chips on rows]
    W --> F --> UI
  end
  today -.-> target