Invitations and Onboarding

How users are invited, registered, scoped to clients/projects, and synced with Auth0.

Actor types

The platform supports these operational personas:

Persona	System type or role	Typical entry point
Platform Admin	`ROLE_ADMIN`	`/admin`
Client Admin	client membership role and web portal access	`/client`
Client Supervisor	supervisor role and project/client scope	`/supervisor`
Payroll Manager	payroll role and client/project scope	`/payroll`
Client Finance	finance role and client scope	`/finance`
Electrician	electrician role and project assignment	mobile API or `/electrician`

Invitation surfaces

There are two registration route families:

Route	Purpose
`/register/invite/{token}`	General invitation registration flow.
`/register/client-user/{token}`	Client-user invitation registration flow.
`/api/invite-user`	API endpoint for creating invitations.
`/api/invite-user/resend`	API endpoint for resending invitations.
`/api/projects/{projectId}/invitations`	Project invitation listing.

Admin and client portal controllers also expose user and invitation management routes. The client portal has pending and expired invitation screens plus resend/cancel actions.

Onboarding sequence

Admin or client admin creates invitation
  -> invitation stores user details, client/project context, and token
  -> email service sends invite link
  -> invited user registers through token route
  -> user is created or linked
  -> Auth0 identity is created or synced
  -> client membership and project assignment define operational scope

Auth0 relationship

Auth0 handles authentication. The app stores its own user, membership, and project assignment records. This split is important:

Auth0 decides whether the person can authenticate.
Symfony security and app user records decide what portal/API area they can access.
Client/project memberships decide what business records they can see.

The command app:sync-users-to-auth0 exists for reconciling app users with Auth0. Auth0 setup and diagnostic scripts also exist under scripts/ and app/src/Command.

Scope after onboarding

For a user to be useful after registration, they need at least one of:

platform admin role
client membership
project team assignment
payroll/finance scope to one or more clients or projects

A login without business scope can authenticate but may see empty portal data.