ModulesOrg OnboardingFeaturesOrg Setup Wizard

Org Setup Wizard

The setup wizard is a 6-step multi-step form at /setup that guides new customers through creating their organization.

Flow

Invite Code → Org Details → Admin Profile → SSO Config → Validate & Select Co-Admin → Complete

Step 1: Invite Code

  • User enters an invite code
  • Backend validates the code and returns a short-lived setup JWT
  • The JWT carries invite_code_id and purpose: "setup"

Step 2: Organization Details

  • User provides: organization name, ERP data source, safety system, optional logo
  • Backend creates the org with a unique slug (collision-safe)
  • A new setup JWT is issued with the org_id embedded

Step 3: Admin Profile

  • User enters their name and email
  • Backend creates the founding master_admin user

Step 4: SSO Configuration

  • User enters their Microsoft Entra app registration credentials:
    • Tenant ID
    • Client ID
    • Client Secret
  • The step shows the two redirect URIs to register in the app registration — web and mobile — built from the address the wizard is open on
  • The client secret is encrypted with AES-256-GCM before storage

Step 5: Validate & Select Co-Admin

  • Backend validates the Entra credentials by acquiring a token
  • On success, fetches all directory users via Microsoft Graph API
  • User selects a second person from the list to serve as co-administrator
  • Minimum 2 master admins are required

Step 6: Complete

  • The co-admin is created as master_admin
  • The organization status is set to active
  • User is sent to the sign-in page to sign in to their new organisation

Safety System

As part of Step 2, you choose the organization’s safety system: Lacroo Safety (the default, no external fields) or Beakon. This choice is a one-time decision — it is stored on the org at creation and shown read-only afterwards in org settings (Org Settings → Organization), alongside a “set at setup” note.

The safety system is the single source of truth for which external-reference fields appear elsewhere in the product:

  • Beakon adds a “Beakon Project ID” field on projects, and “Beakon Code” and “Beakon ID” fields on field users.
  • Lacroo Safety adds no extra fields — projects and field users show only their standard fields.

State Management

Wizard state is managed entirely in React memory via a custom useWizardState hook. State is lost on page refresh — this is acceptable for a one-time setup flow. The setup token is the critical piece of state and is passed to every server action.

Sequence Diagram

Browser              Next.js BFF           Go API              Database
  |                     |                    |                     |
  |-- Enter code ------>|                    |                     |
  |                     |-- POST invite ---->|                     |
  |                     |                    |-- GetByCode ------->|
  |                     |                    |<-- invite row ------|
  |                     |<-- setup JWT ------|                     |
  |<-- token -----------|                    |                     |
  |                     |                    |                     |
  |-- Org details ----->|                    |                     |
  |                     |-- POST org ------->|                     |
  |                     |                    |-- CreateOrg ------->|
  |                     |<-- org + new JWT --|                     |
  |                     |                    |                     |
  |   ... (steps 3-6 follow the same pattern) ...                 |
OverviewSSO Configuration