SPEC 020 — Onboarding and Welcome

Field	Value
Status	DRAFT
Priority	P0 — Launch-Critical
Backend	`equa-server/modules/referral/` (company info), `equa-server/modules/agent/` (AI-powered onboarding)
Frontend	`equa-web/src/modules/welcome/`, `equa-web/src/shared/components/onboard-checklist/`

1. Feature Purpose

The onboarding flow guides new users from registration through profile completion, PIN setup, and organization creation. It operates on two tracks: a traditional flow (welcome page → profile form → PIN → all-set) and an AI-powered flow (pre-registration prompt → Equanaut analysis → organization build → first-login showcase). The onboarding checklist persists post-onboarding as a guide within organization dashboards, tracking setup completion across org details, members, cap table, securities, documents, billing, and more.

2. Current State (Verified)

2.1 Welcome Page

Detail	Value
File	`equa-web/src/modules/welcome/pages/welcome-page.tsx`
Component	`WelcomePage`
Content	Welcome banner image, three feature panels (Control & Empower Agreements, Safeguard Your Entity, Protect & Manage Ownership)
Actions	”BUILD YOUR PROFILE” button → `buildProfilePath`, “SKIP” link → `portfolioPath`
Theme	Sets `Themes.EQUA` on mount via `AppContext.dispatch`

2.2 Build Profile Page

Detail	Value
File	`equa-web/src/modules/welcome/pages/build-profile-page.tsx`
Component	`BuildProfile`
Form	Reuses `ProfileForm` from profile module
Data loader	`loadProfile()`
Initial values	Pre-populated from existing profile (firstName, lastName, photo, email, phone, DOB, address, links, website)
File upload	`postFile(httpClient)('profile/{userId}/file', files)`
On submit	Calls `updateUserProfile()`, then creates addresses via `createAddress()`, then navigates to `profilePINPath`
Skip	Navigates directly to `profilePINPath`
State	Redux `state.user` for user context

2.3 Add PIN Page

Detail	Value
File	`equa-web/src/modules/welcome/pages/add-pin-page.tsx`
Component	`AddPinPage`
Form	Reuses `AccountSettingsForm` from profile module
On submit	Calls `editAccount(httpClient)({ user: user.id }, { pin })`, navigates to `allSetPath` on success
Skip	Navigates directly to `allSetPath`
Edit mode	Detects if path contains `/edit/` to differentiate first-time vs. edit

2.4 All Set Page

Detail	Value
File	`equa-web/src/modules/welcome/pages/all-set-page.tsx`
Component	`AllSetPage`
Content	Checkmark illustration, “You’re All Set!” heading, description text
Actions	”VIEW YOUR PORTFOLIO” → `portfolioPath`, “ONBOARD NEW ORGANIZATION” → `organizationListPath`

2.5 User Dashboard Redirect Logic

Detail	Value
File	`equa-web/src/modules/user-dashboard/dashboard.tsx`
Behavior	On login: 0 orgs → `welcomePath`; 1 org → that org’s page; 2+ orgs → org list

2.6 Onboarding Checklist

Detail	Value
File	`equa-web/src/shared/components/onboard-checklist/onboard-checklist.tsx`
Component	`OnboardChecklistComponent`
State management	Redux `checklistReducer` with `CHECKLIST_EXPANDED` / `CHECKLIST_COLLAPSED` actions
Data source	`getUserState()` + `getTasks()` API calls
Permission check	`loadChecklistPermissions(user)` loads permissions before rendering
Task tracking	Tracks completion of: org details, members, cap table, securities, legends, convertibles, plans, roles, billing
Paths covered	`organizationDetailsPath`, `organizationMembersPath`, `captablePath`, `organizationSecuritiesPath`, `organizationLegendsPath`, `convertibleInstrumentsPath`, `plansPath`, `rolesPath`, `selectYourPlanPath`
UI features	Expandable/collapsible, rocket icon progress indicator, help link, completion checkmarks

2.7 Checklist Reducer

Detail	Value
File	`equa-web/src/logic/reducers/checklist-reducer.ts`
Default state	`{ expanded: true }`
Actions	`CHECKLIST_EXPANDED` → `{ expanded: true }`, `CHECKLIST_COLLAPSED` → `{ expanded: false }`

2.8 AI-Powered Onboarding (via Equanaut)

Detail	Value
Backend	`equa-server/modules/agent/src/onboarding/`
Frontend	`equa-web/src/modules/equanaut/components/OnboardingFlow.tsx`
Status flow	`pending_signup` → `pending_setup` → `setting_up` → `ready` → `first_login` → `completed`
Pre-registration	User provides email + free-text company description → creates onboarding context
Post-registration	Onboarding context linked to user → AI analyzes description → builds organization
First login	`/agent/onboarding/first-login` checks for pending context, returns welcome message and setup result
Showcase	Presents extracted data (org info, members, equity, documents) with confidence scores and inline corrections
Clarification	AI generates questions for ambiguous inputs; user answers to refine the analysis

2.9 Company Info Collection (Waitlist Phase)

Detail	Value
Backend	`equa-server/modules/referral/src/referral.ts` — `addUserCompanyInfo()`
Fields	Company name, email, phone, organization type (public/private), schedule tool (zoom/skype/meet), number of security holders
Reward	Generates a scratch card reward (`RewardType.organizationInfo`) on first submission
Notification	Sends company info to `info@equastart.io`
Upsert	Updates existing record if user already submitted company info

3. Data Model

CompaniesInfo

Column	Type	Constraints
id	uuid	PK
email	citext	Company contact email
name	text	Company name
phoneNumber	text
numberSecurityHolder	number	Expected member/holder count
organizationType	OrganizationType	Enum: public (1), private (2), private (3)
scheduleTool	ToolType	Enum: zoom (1), skype (2), meet (3)
user	uuid	FK to Users, UNIQUE

RegistrationMetadata

Column	Type	Constraints
user	uuid	PK, FK to Users
value	jsonb	Arbitrary registration metadata blob

UserStates (for checklist tracking)

Column	Type	Constraints
user	uuid	PK, FK to Users
data	jsonb	Contains checklist completion state

ChecklistState (Redux)

Field	Type	Default
expanded	boolean	`true`

OnboardingContext (AI flow, in-memory/persistence TBD)

Field	Type	Description
id	string	UUID
userId	uuid?	Linked post-registration
email	string	User’s email
initialPrompt	string	Free-text company description
status	OnboardingStatus	Status enum (see section 2.8)
setupResult	OnboardingSetupResult?	Build output
analysisResult	OnboardingAnalysisResult?	AI extraction results
clarifyingQuestions	ClarifyingQuestion[]?	Questions for ambiguous data
expiresAt	Date	Context expiry

4. API Endpoints

Traditional Onboarding

Method	Path	Auth	Description
PUT	`/api/v1/profile/:id`	Session	Update profile during build-profile step
POST	`/api/v1/profile/:id/file`	Session	Upload profile image
POST	`/api/v1/address/:entity`	Session	Create address during profile build
PUT	`/api/v1/account/:user`	Session	Set 4-digit PIN
GET	`/api/v1/user-state/:user`	Session	Get checklist progress state
PUT	`/api/v1/user-state/:user`	Session	Update checklist progress state
GET	`/api/v1/tasks/:organization`	Session	Get task completion status for checklist

Company Info (Waitlist)

Method	Path	Auth	Description
POST	`/api/v1/referral/company-info`	Session	Submit company information

AI-Powered Onboarding

Method	Path	Auth	Description
POST	`/api/v1/agent/onboarding/create`	Public	Create onboarding context with email + description
GET	`/api/v1/agent/onboarding/:id`	Public	Get onboarding context status
POST	`/api/v1/agent/onboarding/link`	Session	Link user to existing onboarding context
POST	`/api/v1/agent/onboarding/setup`	Session	Trigger AI organization build
POST	`/api/v1/agent/onboarding/analyze`	Session	Trigger AI analysis of submitted data
GET	`/api/v1/agent/onboarding/first-login`	Session	Check for pending onboarding on first login
POST	`/api/v1/agent/onboarding/complete`	Session	Mark onboarding as done
GET	`/api/v1/agent/onboarding/questions/:id`	Public	Get clarifying questions
POST	`/api/v1/agent/onboarding/clarify`	Session	Submit clarification answer
GET	`/api/v1/agent/onboarding/showcase/:id`	Public	Get showcase data for review
POST	`/api/v1/agent/onboarding/correct`	Session	Submit correction to extracted data
POST	`/api/v1/agent/onboarding/build`	Session	Build organization from analysis

5. Frontend Components

Module: `equa-web/src/modules/welcome/`

Component	File	Purpose
`WelcomePage`	`pages/welcome-page.tsx`	Landing page with feature panels and “Build Profile” CTA
`BuildProfile`	`pages/build-profile-page.tsx`	Profile form with photo upload, fields, address, links
`AddPinPage`	`pages/add-pin-page.tsx`	4-digit PIN setup with confirmation
`AllSetPage`	`pages/all-set-page.tsx`	Completion page with “View Portfolio” and “Onboard New Org”

Shared: `equa-web/src/shared/components/onboard-checklist/`

Component	File	Purpose
`OnboardChecklistComponent`	`onboard-checklist.tsx`	Persistent checklist widget on org dashboard

Reused from Profile Module

Component	Source	Purpose
`ProfileForm`	`modules/profile/components/profile-form.tsx`	Name, image, phone, DOB, links, website fields
`AccountSettingsForm`	`modules/profile/components/account-settings-form.tsx`	4-digit PIN form

AI Onboarding (from Equanaut Module)

Component	File	Purpose
`OnboardingFlow`	`modules/equanaut/components/OnboardingFlow.tsx`	AI-guided org setup
`MVPShowcase`	`modules/equanaut/components/MVPShowcase.tsx`	Review extracted org data
`ClarifyingQuestionsFlow`	`modules/equanaut/components/ClarifyingQuestionsFlow.tsx`	Q&A for ambiguous inputs

Post-Onboarding Dashboard Empty State (PR #512)

When a new organization has no cap table data, no documents, and no activity, the organization dashboard renders an onboarding-focused empty state instead of a page full of zero-valued metrics.

Component	File	Purpose
`DashboardEmptyState`	`modules/organization-dashboard/components/empty-state/empty-state.tsx`	3-step onboarding guide (create cap table, invite team, upload documents) rendered when all dashboard metrics are zero
`RecentActions` (updated)	`modules/organization-dashboard/components/recent-actions/recent-actions.tsx`	Replaced the 6-year-old “Coming Soon” placeholder with a “No recent activity” empty state

Detection rule: DashboardEmptyState is shown when every rolling metric on the organization dashboard resolves to zero (no shareholders, no issued shares, no pending actions). Any non-zero metric reverts the dashboard to its normal rendering. Relationship to AI onboarding: The Equanaut module already surfaces onboarding prompts at the organization-creation step (via OnboardingFlow). DashboardEmptyState picks up the next empty-state phase after the organization exists but before any data has been populated. Source: equa-web/src/modules/organization-dashboard/components/empty-state/*, dashboard.test.tsx (PR #512 Workstream B, 2026-04-01; closes issue #503).

Redux

Reducer	File	Purpose
`checklistReducer`	`logic/reducers/checklist-reducer.ts`	Expand/collapse state for onboarding checklist

6. Business Rules

Welcome redirect: Users with zero organizations are redirected to the welcome page on login. Users with one org go directly to that org. Users with multiple orgs see the org list.
Profile form is skippable: Users can skip profile building and PIN setup to reach the “All Set” page.
PIN is optional: The PIN setup step can be skipped. PIN is used for document signing, not authentication.
Profile image types: Only PNG, JPG, JPEG accepted. Square images recommended.
Address creation: During profile build, addresses are created via separate API calls after the profile update succeeds.
Company info reward: First-time company info submission generates one scratch card reward. Subsequent submissions update the record without generating additional rewards.
Theme setting: Welcome page sets Themes.EQUA on mount, ensuring consistent branding during onboarding.
Checklist tracks completion across 9+ setup tasks: org details, members, cap table, securities, legends, convertibles, plans, roles, billing/subscription.
Checklist is permission-aware: Tasks only appear if the user has the relevant permissions (e.g., cap table tasks require viewCapTable).
AI onboarding is optional: Users can follow the traditional flow without engaging the Equanaut pipeline.
AI onboarding pre-registration: Onboarding context can be created before the user has an account, then linked after signup.
Onboarding context expiry: AI onboarding contexts expire after a set period if not completed.
Showcase corrections: Users can edit AI-extracted data before the organization is finalized.
First login detection: The system checks for a pending AI onboarding context on first login and presents the welcome message and setup results if found.

7. Acceptance Criteria

8. Risks

Risk	Impact	Mitigation
Two parallel onboarding tracks (traditional + AI) with no unified state	Confusion about which path the user is on	Add a mode selector or auto-detect based on onboarding context existence
Checklist relies on `getUserState()` + `getTasks()` separate API calls	Extra latency on org dashboard load	Batch into a single endpoint or cache aggressively
Profile form reuse means changes to profile module affect onboarding	Regression risk from unrelated profile changes	Integration tests covering the build-profile flow
AI onboarding context stored in memory (per SPEC 018 risk)	Lost on server restart	Persist to database before production launch
Company info still references `equastart.io` email	Outdated branding	Update to current domain
`organizationType` enum has two values mapping to “private” (2 and 3)	Ambiguous data	Clarify enum or consolidate values
Skip buttons allow users to complete onboarding with empty profile and no PIN	Users may miss critical setup	Show a reminder on the checklist; track skip rate to assess impact
Checklist module counter (`let count = 0`) is module-scoped	Potential stale state across renders	Refactor to React state or ref

Platform Architecture

Compliance & Security

Feature Specifications

Releases

Developer Onboarding

Business

Reference & Templates

Onboarding and Welcome

SPEC 020 — Onboarding and Welcome

1. Feature Purpose

2. Current State (Verified)

2.1 Welcome Page

2.2 Build Profile Page

2.3 Add PIN Page

2.4 All Set Page

2.5 User Dashboard Redirect Logic

2.6 Onboarding Checklist

2.7 Checklist Reducer

2.8 AI-Powered Onboarding (via Equanaut)

2.9 Company Info Collection (Waitlist Phase)

3. Data Model

CompaniesInfo

RegistrationMetadata

UserStates (for checklist tracking)

ChecklistState (Redux)

OnboardingContext (AI flow, in-memory/persistence TBD)

4. API Endpoints

Traditional Onboarding

Company Info (Waitlist)

AI-Powered Onboarding

5. Frontend Components

Module: `equa-web/src/modules/welcome/`

Shared: `equa-web/src/shared/components/onboard-checklist/`

Reused from Profile Module

AI Onboarding (from Equanaut Module)

Post-Onboarding Dashboard Empty State (PR #512)

Redux

6. Business Rules

7. Acceptance Criteria

8. Risks

​SPEC 020 — Onboarding and Welcome

​1. Feature Purpose

​2. Current State (Verified)

​2.1 Welcome Page

​2.2 Build Profile Page

​2.3 Add PIN Page

​2.4 All Set Page

​2.5 User Dashboard Redirect Logic

​2.6 Onboarding Checklist

​2.7 Checklist Reducer

​2.8 AI-Powered Onboarding (via Equanaut)

​2.9 Company Info Collection (Waitlist Phase)

​3. Data Model

​CompaniesInfo

​RegistrationMetadata

​UserStates (for checklist tracking)

​ChecklistState (Redux)

​OnboardingContext (AI flow, in-memory/persistence TBD)

​4. API Endpoints

​Traditional Onboarding

​Company Info (Waitlist)

​AI-Powered Onboarding

​5. Frontend Components

​Module: equa-web/src/modules/welcome/

​Shared: equa-web/src/shared/components/onboard-checklist/

​Reused from Profile Module

​AI Onboarding (from Equanaut Module)

​Post-Onboarding Dashboard Empty State (PR #512)

​Redux

​6. Business Rules

​7. Acceptance Criteria

​8. Risks

SPEC 020 — Onboarding and Welcome

1. Feature Purpose

2. Current State (Verified)

2.1 Welcome Page

2.2 Build Profile Page

2.3 Add PIN Page

2.4 All Set Page

2.5 User Dashboard Redirect Logic

2.6 Onboarding Checklist

2.7 Checklist Reducer

2.8 AI-Powered Onboarding (via Equanaut)

2.9 Company Info Collection (Waitlist Phase)

3. Data Model

CompaniesInfo

RegistrationMetadata

UserStates (for checklist tracking)

ChecklistState (Redux)

OnboardingContext (AI flow, in-memory/persistence TBD)

4. API Endpoints

Traditional Onboarding

Company Info (Waitlist)

AI-Powered Onboarding

5. Frontend Components

Module: `equa-web/src/modules/welcome/`

Shared: `equa-web/src/shared/components/onboard-checklist/`

Reused from Profile Module

AI Onboarding (from Equanaut Module)

Post-Onboarding Dashboard Empty State (PR #512)

Redux

6. Business Rules

7. Acceptance Criteria

8. Risks