User Onboarding Flow
Relevant source files
The following files were used as context for generating this wiki page:
The User Onboarding Flow in the Flow platform is a multi-step guided experience designed to transition new users from registration to their first successful agent interaction in under two minutes. The flow encompasses use-case selection, document ingestion, and the collection of user preferences to establish a personalized "second brain" environment.
This system is built using Next.js (App Router) on the frontend and interacts with FastAPI backend endpoints for workspace identification, preference storage, and knowledge indexing. It ensures that the user's workspace is properly configured with initial data and personal context before they enter the main execution environment.
Sources: README.md:16-16, apps/web/src/app/(app)/onboarding/page.tsx:39-44
Core Onboarding Stages
The onboarding process is divided into functional steps that prioritize immediate utility.
Use-Case Selection
Upon entering the onboarding page, users are presented with three primary entry points. This selection determines whether the user is guided to a document upload step or redirected straight to the execution interface.
| Use Case | Description | Icon |
|---|---|---|
| Documents | Upload PDFs, notes, or articles for query retrieval. | BookOpen |
| Automation | Schedule recurring agent pipelines over the knowledge base. | Sparkles |
| Code | Write and execute Python in a sandbox environment. | Globe |
Sources: apps/web/src/app/(app)/onboarding/page.tsx:16-33
Knowledge Ingestion
If the "Documents" use case is selected, the flow proceeds to a file upload interface. This stage supports .pdf, .md, .txt, and .docx formats (up to 20MB). The backend subsequently chunks and embeds these files for retrieval-augmented generation (RAG).
The logic follows these steps:
- Validate the existence of a
workspace_idvia the/api/v1/auth/meendpoint. - Accept a file via a hidden file input triggered by a stylized button.
- Transmit the file using
FormDatato/api/v1/knowledge/upload. - Redirect the user to the
/runpage upon successful indexing.
Sources: apps/web/src/app/(app)/onboarding/page.tsx:61-83, apps/web/src/app/(app)/onboarding/page.tsx:115-135
Preference Collection (Onboarding Questionnaire)
The OnboardingQuestionnaire component is a 7-step modal experience that gathers technical and stylistic preferences to populate the user's workspace profile.
Questionnaire Structure
The questionnaire utilizes a mix of "chips" (predefined suggestions) and free-text inputs. It tracks progress through a state-controlled step index (0-6).
| Step Class | Topic | Optional |
|---|---|---|
tooling | Preferred programming languages. | No |
domain | Professional field (e.g., DevOps, Data Science). | No |
style | Formatting preferences (e.g., Bullet points). | No |
goal | Current learning or project objectives. | No |
veto | Disliked patterns or technologies. | Yes |
tooling | Tech stack preferences (e.g., FastAPI, Next.js). | Yes |
channel | Code presentation style. | Yes |
Sources: apps/web/src/components/preferences/OnboardingQuestionnaire.tsx:29-87
Data Submission
Answers are compiled into an array of AnswerEntry objects. The component ensures that skipped optional questions do not submit empty data to the backend.
The diagram shows the logic flow from user interaction within the questionnaire to the final API submission.
Sources: apps/web/src/components/preferences/OnboardingQuestionnaire.tsx:125-149, apps/web/tests/OnboardingQuestionnaire.test.tsx:121-140
Identity Synthesis (SOUL.md)
Preferences gathered during onboarding contribute to the generation of a SOUL.md file (also referred to as the Persona). This block of text is injected as the first system message in every agent run to provide persistent context about the user's identity and requirements.
SOUL Questionnaire
A specialized "SOUL" questionnaire can be triggered to regenerate this identity block. It focuses on:
- Name and professional role.
- Personal passions and drivers.
- Communication style and level of detail.
- Prohibited assistant behaviors.
Sources: apps/web/src/components/preferences/PersonaSection.tsx:14-20, apps/web/src/components/preferences/PersonaSection.tsx:132-136
Regeneration Logic
The system detects when user preferences have changed since the last persona generation, marking the current SOUL.md as "stale."
The flow describes how preference updates lead to the regeneration of the user's core identity block.
Sources: apps/web/src/components/preferences/PersonaSection.tsx:126-130, apps/web/src/components/preferences/PersonaSection.tsx:146-150
Technical Implementation Details
State Management and Analytics
The onboarding page uses useRef to maintain a stable reference to the Next.js router and tracks specific events for funnel analysis.
- Events Tracked:
onboarding_viewed: Triggered when the component mounts and workspace is confirmed.onboarding_usecase_selected: Captured when a user clicks "Continue" on Step 1.onboarding_first_doc_uploaded: Dispatched after a successful file POST.
Sources: apps/web/src/app/(app)/onboarding/page.tsx:55-58, apps/web/src/app/(app)/onboarding/page.tsx:61-75
API Integration
Onboarding components utilize a centralized apiFetch utility for authenticated requests.
| Endpoint | Method | Purpose |
|---|---|---|
/api/v1/auth/me | GET | Retrieve workspace ID and user context. |
/api/v1/knowledge/upload | POST | Upload initial RAG documents. |
/api/v1/preferences/onboarding | POST | Save preference questionnaire answers. |
/api/v1/personas/me/questionnaire | POST | Submit specific SOUL questionnaire answers. |
Sources: apps/web/src/app/(app)/onboarding/page.tsx:52-52, apps/web/src/components/preferences/OnboardingQuestionnaire.tsx:155-159, apps/web/src/components/preferences/PersonaSection.tsx:55-60
Summary
The User Onboarding Flow is a critical entry mechanism for the Flow platform, ensuring that users are not greeted by an empty state. By combining use-case selection, immediate document indexing, and a structured preference questionnaire, the system establishes both the data (Knowledge) and the behavioral constraints (Persona) required for effective agent performance. Significant aspects include the versioned SOUL.md identity block and the multi-step file ingestion process that feeds the RAG pipeline.