State Machine

Complete state machine documentation with all states, transitions, and state definitions.

Overview

The conversational system uses a state machine to manage user interactions during content creation. The state machine adapts its flow based on the selected content type (affirmation, guided meditation, or ritual).

Complete State Diagram

stateDiagram-v2 [*] --> Idle: User opens app Idle --> TypeSelection: User clicks Create TypeSelection --> AffirmationFlow: Selects Affirmation TypeSelection --> MeditationFlow: Selects Meditation TypeSelection --> RitualFlow: Selects Ritual state AffirmationFlow { [*] --> Greeting Greeting --> IntentGathering: User responds IntentGathering --> StatementCollection: Intent received StatementCollection --> VoiceSelection: Statements complete VoiceSelection --> Review: Voice selected Review --> Confirmed: User confirms Review --> StatementCollection: User modifies Confirmed --> Generating Generating --> Complete } state MeditationFlow { [*] --> Greeting Greeting --> IntentGathering: User responds IntentGathering --> DurationSelection: Intent received DurationSelection --> PracticeTypeSelection: Duration selected PracticeTypeSelection --> ImageryGathering: Practice type selected ImageryGathering --> VoiceSelection: Imagery provided/skipped VoiceSelection --> Review: Voice selected Review --> Confirmed: User confirms Review --> DurationSelection: User modifies Confirmed --> Generating Generating --> Complete } state RitualFlow { [*] --> Greeting Greeting --> IntentGathering: User responds IntentGathering --> ContextGathering: Intent received ContextGathering --> DurationSelection: Context complete DurationSelection --> PracticeTypeSelection: Duration selected PracticeTypeSelection --> IdentityLanguageGathering: Practice type selected IdentityLanguageGathering --> EmotionalAnchoringGathering: Identity statements complete EmotionalAnchoringGathering --> VoiceSelection: Emotional goal provided VoiceSelection --> Review: Voice selected Review --> Confirmed: User confirms Review --> ContextGathering: User modifies Confirmed --> Generating Generating --> Complete } Complete --> Idle: Return to library Complete --> Practice: Start practice Practice --> Idle: Practice complete

State Definitions

Idle

Description: Initial state when user opens the app or returns to the main interface.

Actions: None

Transitions:

user_clicks_create → TypeSelection

TypeSelection

Description: User selects which content type to create (affirmation, guided meditation, or ritual).

Actions: Display three options with brief explanations

Transitions:

selects_affirmation → AffirmationFlow.Greeting
selects_meditation → MeditationFlow.Greeting
selects_ritual → RitualFlow.Greeting

Greeting

Description: System greets user and explains the creation process. Content varies based on selected type.

Actions: Send greeting message, explain process

Transitions:

user_responds → IntentGathering

IntentGathering

Description: System asks what the user wants to create. Question adapts to content type.

Questions Asked:

Affirmations: "What do you want to affirm or strengthen?"
Meditations: "What state would you like to access?"
Rituals: "What is changing in your life right now?"

Data Saved: intent: string

Transitions:

intent_received → Next state (varies by type)

ContextGathering

Description: Rituals only. System asks why this change matters and what the deeper meaning is.

Questions Asked:

"Why does this matter to you?"
"What's the deeper meaning or significance?"

Data Saved: context: jsonb {why_matters: string, deeper_meaning: string, life_moment: string}

Transitions:

context_complete → DurationSelection

StatementCollection

Description: Affirmations only. System asks for 3-7 specific affirmation statements.

Questions Asked:

"What specific statements feel true for you? Share 3-7 statements in present tense."

Data Saved: statements: string[]

Transitions:

statements_complete → VoiceSelection

DurationSelection

Description: Meditations and Rituals only. System asks for preferred duration.

Questions Asked:

Meditations: "How long would you like this meditation? (5-20 minutes)"
Rituals: "How long would you like this ritual? (10-30 minutes)"

Data Saved: duration_preference: integer

Transitions:

duration_selected → PracticeTypeSelection

PracticeTypeSelection

Description: Meditations and Rituals only. System asks what practice type to include.

Questions Asked:

"What practice type? Breath work, body scanning, visualization, or combination?"

Data Saved: practice_type: 'breath-work' | 'body-scanning' | 'visualization' | 'combination'

Transitions:

practice_type_selected → Next state (varies by type)

ImageryGathering

Description: Meditations only. System asks for specific imagery or visualization preferences.

Questions Asked:

"Any specific imagery or visualization you'd like included?"

Data Saved: imagery: string | null

Transitions:

imagery_provided_or_skipped → VoiceSelection

IdentityLanguageGathering

Description: Rituals only. System asks for identity-level language that resonates.

Questions Asked:

"What identity-level language resonates with you? How do you want to speak to yourself?"

Data Saved: identity_statements: string[]

Transitions:

identity_statements_complete → EmotionalAnchoringGathering

EmotionalAnchoringGathering

Description: Rituals only. System asks what emotional state to anchor.

Questions Asked:

"What emotional state do you want to anchor? What do you want to feel?"

Data Saved: emotional_goal: string

Transitions:

emotional_goal_provided → VoiceSelection

VoiceSelection

Description: System asks for voice preference. Available options vary by content type.

Questions Asked:

"Would you like to use your voice or a selected voice?"

Data Saved: voice_id: uuid, voice_type: 'user' | 'standard' | 'premium'

Transitions:

voice_selected → Review

Review

Description: System presents complete summary of all gathered information for user confirmation.

Actions: Display summary with all collected data

Transitions:

user_confirms → Confirmed
user_modifies → Returns to appropriate earlier state

Confirmed

Description: User has confirmed all details. System prepares for generation.

Actions: Validate all required data, check credit availability

Transitions:

ready_to_generate → Generating
insufficient_credits → Show credit purchase prompt

Generating

Description: System generates content text (LLM) and audio (TTS). Background process.

Actions: Call LLM with all context, generate text, synthesize audio, consume credit

Data Saved: content_text: text, structure: jsonb, audio_url: string, audio_duration: integer, content_type: enum

Transitions:

generation_complete → Complete
generation_failed → Show error, return to Review

Complete

Description: Content is generated and saved. User can practice immediately or return to library.

Actions: Display success message, show "Practice Now" and "Save for Later" options

Transitions:

practice_now → Practice
save_for_later → Idle

Practice

Description: User is practicing the created content. Audio playback state.

Actions: Play audio, allow pause/resume, track playback position

Transitions:

practice_complete → Idle (save last_played_at, increment play_count)
pause → Practice (paused state)
resume → Practice (playing state)

State Context

Each state maintains context about the conversation:

content_type: 'affirmation' | 'guided_meditation' | 'ritual'
intent: string
context: jsonb (rituals only)
statements: string[] (affirmations only)
duration_preference: integer (meditations and rituals)
practice_type: string (meditations and rituals)
imagery: string | null (meditations only)
identity_statements: string[] (rituals only)
emotional_goal: string (rituals only)
voice_id: uuid
voice_type: string

Error Handling

Credit Insufficient: If user doesn't have enough credits, system shows credit purchase prompt and remains in Confirmed state.

Generation Failure: If generation fails, system returns to Review state with error message, allowing user to modify and retry.

Network Error: System retries up to 3 times, then shows error and returns to Review state.

Type-Specific Flows

Affirmation Flow

States: Greeting → IntentGathering → StatementCollection → VoiceSelection → Review → Confirmed → Generating → Complete

Key Difference: No duration or practice type selection. Focuses on statements and voice.

Meditation Flow

States: Greeting → IntentGathering → DurationSelection → PracticeTypeSelection → ImageryGathering → VoiceSelection → Review → Confirmed → Generating → Complete

Key Difference: Includes duration, practice type, and optional imagery. No context or identity language gathering.

Ritual Flow

States: Greeting → IntentGathering → ContextGathering → DurationSelection → PracticeTypeSelection → IdentityLanguageGathering → EmotionalAnchoringGathering → VoiceSelection → Review → Confirmed → Generating → Complete

Key Difference: Most comprehensive flow. Includes context, identity language, and emotional anchoring—unique to rituals.