> ## Documentation Index > Fetch the complete documentation index at: https://docs.equa.cc/llms.txt > Use this file to discover all available pages before exploring further. # 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 `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 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 |