Onboarding and Welcome

New user welcome flow, profile building, PIN setup, company info collection, onboarding checklist, and AI-powered organization setup

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 [e-mail]
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

Redux

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

---

6. Business Rules

1. 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.
2. Profile form is skippable: Users can skip profile building and PIN setup to reach the “All Set” page.
3. PIN is optional: The PIN setup step can be skipped. PIN is used for document signing, not authentication.
4. Profile image types: Only PNG, JPG, JPEG accepted. Square images recommended.
5. Address creation: During profile build, addresses are created via separate API calls after the profile update succeeds.
6. Company info reward: First-time company info submission generates one scratch card reward. Subsequent submissions update the record without generating additional rewards.
7. Theme setting: Welcome page sets Themes.EQUA on mount, ensuring consistent branding during onboarding.
8. Checklist tracks completion across 9+ setup tasks: org details, members, cap table, securities, legends, convertibles, plans, roles, billing/subscription.
9. Checklist is permission-aware: Tasks only appear if the user has the relevant permissions (e.g., cap table tasks require viewCapTable).
10. AI onboarding is optional: Users can follow the traditional flow without engaging the Equanaut pipeline.
11. AI onboarding pre-registration: Onboarding context can be created before the user has an account, then linked after signup.
12. Onboarding context expiry: AI onboarding contexts expire after a set period if not completed.
13. Showcase corrections: Users can edit AI-extracted data before the organization is finalized.
14. 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

• New user with 0 orgs is redirected to the welcome page
• Welcome page displays three feature panels and “Build Profile” / “Skip” actions
• Build Profile form pre-populates from existing profile data
• Profile photo upload works with PNG/JPG/JPEG
• Submitting profile navigates to PIN setup page
• PIN validation requires exactly 4 numeric digits with matching confirmation
• Skipping profile or PIN navigates correctly to the next step
• “All Set” page offers “View Portfolio” and “Onboard New Organization” actions
• Onboarding checklist appears on organization dashboard
• Checklist items reflect actual completion status from API
• Checklist expand/collapse state persists via Redux
• Checklist only shows tasks the user has permission to complete
• Company info form collects all required fields and generates a scratch card reward
• AI onboarding: user can create context pre-registration with email + description
• AI onboarding: context links to user after signup
• AI onboarding: analysis extracts entities, equity, and security types
• AI onboarding: clarifying questions appear when confidence is low
• AI onboarding: showcase displays extracted data with inline editing
• AI onboarding: first login detects pending context and shows welcome message

---

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