Company Onboarding Flow

When a new company account is created, a guided onboarding checklist appears on the main dashboard to help admins complete the initial setup. The checklist tracks progress automatically and disappears once everything is done.

The Four Onboarding Steps

Step	Description	Destination
Complete Company Details	Fill in agency name, email, phone, and address	Company Settings
Configure Tenancy Settings	Set deposit protection providers and compliance document types	Tenancy Settings
Add First Property	Add at least one property to the portfolio	Portfolio
Invite Team Members	Invite at least one agent or staff member	Team

How It Works

Auto-detection

Progress is detected automatically by querying live data — you do not need to interact with the checklist itself to mark steps as complete. If you fill in company details through the normal settings page, that step will be marked complete the next time the dashboard loads.

Persistence

Onboarding state is stored in the company_onboarding_progress table (one record per organisation). Progress is resumable — closing the browser or navigating away does not reset your progress.

Visibility rules

The checklist widget:

• Appears above all other dashboard content
• Is hidden automatically once all four steps are complete
• Can be hidden early using the ✕ dismiss button — this stores a dismissed flag and the widget will not reappear

Dashboard Widget

The CompanyOnboardingChecklist component renders the following UI elements:

• Header — "Set Up Your Agency" title with a dismiss (✕) button
• Progress bar — Shows X of 4 steps complete and a percentage fill
• Step list — Each step is a link to the relevant page:
  • ✅ Completed steps show a green checkmark and strikethrough label
  • ➡️ The next recommended step is highlighted with a white card and blue border
  • Remaining incomplete steps are shown in a standard muted style

API Reference

tRPC: companyOnboarding.getProgress

Fetches current onboarding progress for the authenticated organisation.

Returns:

{
  dismissed: boolean;
  allComplete: boolean;
  completedCount: number;
  totalSteps: number;       // always 4
  percentage: number;       // 0–100
  steps: Array<{
    step: string;           // e.g. "company_details"
    label: string;          // Human-readable step name
    description: string;
    href: string;           // Link to the action page
    completed: boolean;
  }>;
}

Step completion is determined dynamically from live data on each call. Newly detected completions are persisted automatically.

tRPC: companyOnboarding.dismiss

Marks the onboarding checklist as dismissed for the authenticated organisation. The action is recorded in the audit log.

Input: none

Returns: void (invalidates the getProgress cache on the client)

Health Endpoints

Two HTTP endpoints are available for infrastructure and deployment health checks.

GET /api/health — Liveness probe

A lightweight check that always returns 200 OK. Runs on the edge runtime with no database dependency. Use this for uptime monitors and load balancer health checks.

{
  "status": "ok",
  "timestamp": "2026-04-07T12:00:00.000Z",
  "version": "abc1234"
}

A HEAD /api/health request is also supported.

GET /api/health/ready — Readiness probe

A deep check that verifies the application is fully operational. Use this for deployment readiness gates (e.g. Kubernetes readinessProbe, post-deploy smoke tests).

Checks performed:

1. DATABASE_URL and NEXTAUTH_SECRET environment variables are present
2. A live database query (SELECT 1) succeeds

Success response (200):

{
  "status": "ok",
  "db": true,
  "timestamp": "2026-04-07T12:00:00.000Z",
  "version": "abc1234"
}

Failure response (503):

{
  "status": "error",
  "db": false,
  "timestamp": "2026-04-07T12:00:00.000Z",
  "error": "Missing env vars: DATABASE_URL"
}

Database Schema

Table: company_onboarding_progress

Column	Type	Description
id	text (PK)	UUID, auto-generated
org_id	text (unique)	One record per organisation
company_details_completed	boolean	Step 1 complete flag
company_details_completed_at	timestamp	When step 1 was completed
tenancy_settings_completed	boolean	Step 2 complete flag
tenancy_settings_completed_at	timestamp	When step 2 was completed
first_property_completed	boolean	Step 3 complete flag
first_property_completed_at	timestamp	When step 3 was completed
invite_team_completed	boolean	Step 4 complete flag
invite_team_completed_at	timestamp	When step 4 was completed
dismissed	boolean	Whether the checklist has been dismissed

The record is created automatically using a getOrCreate pattern when getProgress is first called for an organisation. The implementation is race-condition safe.