Onboarding Flow

When the platform starts with an empty database (no users), it must guide the administrator through a setup wizard before the application can be used.

Decision Table

Scenario	Behavior
API unreachable (network error)	Redirect to /login + show error toast
API reachable + users exist (setup complete)	Redirect to /login
API reachable + no users (setup incomplete)	Redirect to /setup (onboarding wizard)

How It Works

Setup Status Check

On every navigation, the setupGuard (registered as the first router guard) checks the setup status:

1. The guard calls GET /api/setup/status on the first navigation
2. The response is cached in the auth store (setupStatus) — subsequent navigations skip the API call
3. If the API is unreachable, the guard fails open (assumes setup is complete) and redirects to /login with an error toast

Route Protection

• Setup incomplete: All routes except /setup redirect to /setup
• Setup complete: Navigating to /setup redirects to /login
• Network error: Non-login routes redirect to /login

App Initialization (App.vue)

On mount, the app:

1. Calls checkSetupStatus() — fetches and caches the setup status
2. If setup is complete, calls refreshSession() to restore the user session
3. Sets isInitialized = true to render the app

This prevents unnecessary session refresh attempts when the database is empty.

Setup Wizard

The wizard at /setup has two steps:

Step 1: Platform Configuration

• Platform name
• Platform description (optional)
• Calls POST /api/setup/platform

Step 2: SuperAdmin Account

• Email, username, password, first name, last name
• Calls POST /api/setup/superadmin
• Returns an access token for automatic login

Post-Setup

After the superadmin is created:

1. The access token is stored in memory
2. markSetupComplete() updates the cached status
3. The user profile is fetched
4. The app redirects to the dashboard (/)

What Gets Seeded

During setup, the backend creates:

• Default roles (SuperAdmin, Admin, Employee, User)
• Default permissions (all entity:action pairs)
• The SuperAdmin user with all permissions
• Password policy with default values
• Platform configuration record

Security Considerations

• The setup endpoints (/api/setup/platform, /api/setup/superadmin) are only accessible when no users exist
• After the first user is created, these endpoints return 409 Conflict
• The superadmin creation uses a serializable transaction to prevent race conditions
• Rate limiting is applied to all setup endpoints