Перейти к содержанию

Auth & Onboarding

This section describes how users authenticate, how companies and groups are created, and how users are invited to existing companies. It focuses on business flows and user-visible behaviour rather than low-level authentication mechanics.

1. Goals

  • Allow a new user to sign up and start using G-Track with one company as quickly as possible.
  • Transparently support multi-company groups when the same owner operates several legal entities.
  • Provide a clear and safe way to invite additional users into an existing company.
  • Keep the experience simple for small tenants (2 trucks, 1 company) and scalable for larger groups (up to ~500 trucks across multiple companies).

Backend details (Supabase Auth, Laravel Cloud, etc.) are implementation-specific and not covered here. From the product perspective, we assume:

  • Email-based accounts.
  • Email verification.
  • Password-based authentication (with possible SSO in future).

2. Core Concepts

2.1 User

A User is a person with:

  • a unique email address (login),
  • a password (or other auth method in future),
  • optional linked Telegram account (future).

A user can be a member of one or multiple companies.

2.2 Company

A Company represents a single legal entity:

  • one tax base and one main currency,
  • its own set of drivers, vehicles and documents,
  • its own access control (who can see/edit what).

2.3 Group

A Group represents a group of companies (holding). It is created only when needed:

  • When the same owner account creates a second company, the system:
  • implicitly creates a Group,
  • assigns both companies to that Group,
  • informs the user about managing a “group of companies”.

Groups are not visible to small tenants with a single company. They are a structural concept for multi-entity operations.

2.4 User Membership & Roles

The link between a User and a Company is represented as UserMembership:

  • user_id
  • company_id
  • role (Owner, Company Admin, HR Manager, Fleet Manager, Dispatcher, Finance, ReadOnly, or custom in future)

A user can have different roles in different companies. For example:

  • Owner in Logistics CZ,
  • HR Manager in Logistics PL.

Permissions are derived from the role for a given company.

3. User States

From the auth perspective, a user can be in one of the following high-level states:

  1. Unauthenticated
  2. Not logged in.

  3. Can only see: marketing site, login page, sign-up page, password reset page.

  4. Authenticated, no companies

  5. Extremely rare; normally the first sign-up immediately creates a company.

  6. Technically possible in edge cases (e.g. invitation accepted, but company removed).

  7. Authenticated, member of exactly one company

  8. Most common small-tenant case.
  9. The user is automatically redirected into that company’s workspace after login.

  10. No company switcher is shown.

  11. Authenticated, member of multiple companies (within one or more groups)

  12. The user must select which company to work with:
    • either a company chooser screen after login,
    • and/or a company switcher in the top navigation bar.
  13. The current company context affects:
    • visible drivers/vehicles,
    • navigation,
    • permissions (role per company).

4. Flows

4.1 Login

Actors: Any existing user.

Steps:

  1. User opens /login.
  2. Enters email and password.
  3. System validates credentials and email verification status.
  4. If email not verified:
  5. show message and offer to resend verification email.
  6. If credentials are valid:
  7. determine memberships (companies) for this user.
  8. If exactly one company:
    • set that company as current context,
    • redirect to the default landing page (for MVP: Drivers list).
  9. If multiple companies:
    • show a company chooser (list of companies with role badges),
    • after selection, set company context and redirect to landing page.

4.2 Sign-up and Create First Company

Actors: New user (no existing account).

Goal: Quickly create a simple single-company tenant.

Steps:

  1. User opens /signup.
  2. Fills in:
  3. personal details (name, email, password),
  4. basic company details (company name, country, optional VAT ID).
  5. System:
  6. creates the User,
  7. sends email verification,
  8. creates the first Company,
  9. assigns the User as Owner (and Company Admin) of that company.
  10. After confirming email:
  11. user logs in and is redirected directly into their company workspace.
  12. No Group is created at this point.
  13. No company switcher is shown (only one company).

4.3 Create Second Company and Group Creation

Actors: Existing Owner of at least one company.

Goal: Support multi-company structures (group of companies).

Steps:

  1. Authenticated Owner opens Settings → Companies (or similar).
  2. Clicks “Create new company”.
  3. The system shows an informational message, e.g.:

“You are about to create a group of companies under your account.
From now on you will be able to manage multiple legal entities within one group.”

  1. User fills in details for the new company (name, country, VAT, etc.).
  2. System:
  3. if no Group exists yet for this Owner:
    • creates a Group,
    • assigns both the existing and new Company to this Group,
    • marks the Owner as Group Owner.
  4. if Group already exists:
    • simply adds the new Company to the existing Group.
  5. After creation:
  6. the Owner becomes Owner/Admin of the new company,
  7. the UI now shows a company switcher (top bar),
  8. login behaviour changes to “company chooser” when multiple companies are available.

4.4 Invite User to an Existing Company

Actors: Company Admin or Owner.

Goal: Add staff (HR, Fleet, Dispatcher, Finance, etc.) without creating separate tenants.

Steps:

  1. Admin opens Settings → Users in the context of a specific company.
  2. Clicks “Invite user”.
  3. Enters:
  4. invitee email,
  5. desired role for this company (HR Manager, Fleet Manager, etc.).
  6. System:
  7. creates a pending invitation linked to that company and role,
  8. sends an email with an invitation link.

4.5 Accept Invitation

Actors: Invited user (may or may not have an existing account).

Steps:

  1. User opens the invitation link.
  2. If the email is not registered yet:
  3. user is asked to set a password and confirm basic profile details.
  4. email verification may be required (depending on policy).
  5. If the email is already registered:
  6. user logs in (if not already authenticated).
  7. System:
  8. creates a UserMembership for the target Company with the assigned role,
  9. marks the invitation as accepted.
  10. After completion:
  11. if this is the user’s first company, they have now:
    • one active company (simple tenant case),
  12. if they already belong to other companies:
    • the accepted company becomes an additional option in the company chooser / switcher.

4.6 Password Reset

Actors: Any user.

Steps:

  1. From /login, user clicks “Forgot password?”.
  2. Enters email.
  3. System sends a password reset link (if the email exists).
  4. User opens the link and sets a new password.
  5. After reset, user can log in normally; memberships and roles are unchanged.

4.7 Email Verification

Email verification is required for:

  • new sign-ups,
  • potentially changed emails in account settings (future).

If the user attempts to log in without verification:

  • system blocks normal access,
  • shows a message,
  • offers resend verification email.

5. Company Switching

Once a user has memberships in multiple companies:

  • A company chooser screen is shown after login if no current company is selected.
  • A company switcher is shown in the top navigation bar:
  • displays current company name,
  • opens a dropdown with other companies and roles for each,
  • changing company triggers a full context switch for:
    • navigation (Drivers, Vehicles for that company),
    • data (lists and dashboards),
    • permissions (role per company).

The current company context is always visible to avoid mistakes (e.g. creating drivers in the wrong company).

6. Future Extensions

Future extensions, not required for the MVP but considered in the design:

  • SSO / OAuth for corporate customers.
  • Office-level segmentation within a company (branches, depots) with more granular memberships.
  • Group-level management UI (explicit group settings, ownership transfer flows between groups).