CRM: User roles and access control

Technical specification for user roles and access control in the PestControlOS CRM (PWA).

Roles

super_admin: Full system control. All data visibility; full calendar access; contract and job management; lead management; email sending; report deletion (including protected reports); shared account configuration (e.g. email tokens). Custom claim or Firestore staff field: role: 'super_admin'.
admin: Operational management. All scheduling, contracts, jobs, lead management, email sending, document management. Cannot delete protected reports. role: 'admin'.
tech: Field technician. Personal dashboard; personal schedule (own workview only); assigned contracts and jobs only; personal commission tracking; report uploads. No access to other technicians’ data. role: 'tech'. Identity may include contractKey (e.g. james, ian) for Firestore querying and rules.

Firebase Authentication: Google OAuth (or email/password) via Firebase Auth. Role resolved from Firestore staff collection (document keyed by UID or email). Session stored in users/{uid}; role and contractKey set in custom claims (via Admin SDK after sign-up) or read from Firestore on each request.
Client-side: Route guards check role before rendering admin-only or tech-only routes. Redirect or 403 if unauthorised. No sensitive data fetched for disallowed routes.
Firestore rules: Every collection rule checks request.auth != null and, where applicable, request.auth.token.role or request.auth.token.contractKey. Examples: calendar allow read/write only if role in [admin, super_admin] or contractKey matches collection; JobWork allow read only if AssignedTechKey == contractKey or role in [admin, super_admin]; Leads allow write of invoiceStatus only if role in [admin, super_admin].
Cloud Functions: Callables verify context.auth and optionally lookup role/contractKey from Firestore; reject requests that require admin when role is tech.

staff: Documents keyed by UID or email. Fields: displayName, role, contractKey (for techs), email, optional orgId. Used as source of truth for role when custom claims are not used or to refresh claims.

Technicians never see other technicians’ contracts, jobs, or calendar events. Admins see all. Super_admin can additionally delete protected reports and manage shared account config.