NAVIGATION FLOWS

Generated: 2025-11-20
Status: Current as of Flow Engine v1.0

Authentication Flows
Main App Structure
Journal Flow
Guided Journal Flow Engine
Companions Flow
Goals & Progress
Settings & Profile
Flow Engine Templates

Authentication Flows

Unauthenticated Users

┌─────────────┐
│  App Start  │
└──────┬──────┘
       │
       ├─ isAuthenticated = false
       │
       ▼
┌─────────────┐
│ Login Screen│ ◄──┐
└──────┬──────┘    │
       │           │
       ├─ "Sign Up"│
       │           │
       ▼           │
┌─────────────┐   │
│SignUp Screen├───┘
└──────┬──────┘
       │
       ├─ Success
       │
       ▼
   [Main App]

First-Time Users (Authenticated)

┌─────────────────┐
│ Login Success   │
└────────┬────────┘
         │
         ├─ hasJournalEntries = false
         │
         ▼
┌─────────────────┐
│ Welcome Screen  │ (3 seconds, auto-navigate)
│  "Preparing..."  │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│   Main Tabs     │
└─────────────────┘

Returning Users

┌─────────────────┐
│ Login Success   │
└────────┬────────┘
         │
         ├─ hasJournalEntries = true
         │
         ▼
┌─────────────────┐
│   Main Tabs     │ (Skip Welcome)
└─────────────────┘

Main App Structure

┌────────────────────────────────────────┐
│            Main Tabs                   │
├──────────┬──────────┬────────┬─────────┤
│ Journal  │Companions│ Goals  │ Progress│
│  (book)  │ (people) │ (flag) │ (chart) │
└──────────┴──────────┴────────┴─────────┘

Each tab contains its own Stack Navigator.

Journal Flow

Journal Stack Structure

JournalStack
│
├─ JournalHome (Main Screen)
│  └─ Header: "Journal" + UserProfileHeader
│
├─ WriteJournal (fullScreenModal)
│  └─ Blank page journal entry
│
└─ EntryDetail
   └─ View past journal entry

User Journey: Creating a Journal Entry

┌────────────────┐
│  JournalHome   │
└───────┬────────┘
        │
        ├─ Empty State: Shows "Begin Your Journey"
        │  └─ Button: "Start Writing"
        │
        ├─ With Entries: Shows list of entries
        │  └─ Button: + (floating action button)
        │
        ▼
┌────────────────┐
│  GuidedJournal │ (New as of v1.0)
│  Intro Screen  │
└───────┬────────┘
        │
        ├─ Back Arrow (←) → Returns to JournalHome
        │
        ├─ Option 1: "Start Guided Session →"
        │   └─ Goes to 13-step flow (see Flow Engine section)
        │
        └─ Option 2: "Start with Blank Page"
            └─ Goes to WriteJournal screen

WriteJournal Screen (Blank Page)

┌────────────────────┐
│  WriteJournal      │
│  (Modal)           │
├────────────────────┤
│ • Mood picker      │
│ • Text input       │
│ • Voice input      │
│ • Cancel/Save btns │
└─────────┬──────────┘
          │
          ├─ Save → Saves to Supabase
          │         (with orgId)
          │
          └─ Cancel → Back to JournalHome

Guided Journal Flow Engine

Flow Container Architecture

┌──────────────────────────────────────┐
│     FlowContainer                    │
│     (Conductor/Orchestrator)         │
├──────────────────────────────────────┤
│                                      │
│  ┌────────────────────────────────┐ │
│  │   FlowContext (State)          │ │
│  │  • Current step                │ │
│  │  • Session data                │ │
│  │  • Progress tracking           │ │
│  └────────────────────────────────┘ │
│                                      │
│  ┌────────────────────────────────┐ │
│  │   StepRenderer                 │ │
│  │  • Dynamically renders         │ │
│  │    content type components     │ │
│  └────────────────────────────────┘ │
│                                      │
│  ┌────────────────────────────────┐ │
│  │   Content Types                │ │
│  │  • PickerType                  │ │
│  │  • TextPromptType              │ │
│  │  • BreathingType               │ │
│  │  │  • ScriptureType              │ │
│  │  • MessageType                 │ │
│  │  • SummaryType                 │ │
│  └────────────────────────────────┘ │
│                                      │
│  ┌────────────────────────────────┐ │
│  │   Components                   │ │
│  │  • ProgressBar                 │ │
│  │  • NavigationControls          │ │
│  │  • BreathingCircle             │ │
│  │  • IntensitySlider             │ │
│  │  • PickerGrid                  │ │
│  └────────────────────────────────┘ │
└──────────────────────────────────────┘

Guided Session Flow (13 Steps)

Intro Screen
  ↓
─────────────────────────────────────
PHASE 1: OPENING (4 steps)
─────────────────────────────────────
1. Mood Check        (picker)
2. What's Happening  (text-prompt)
3. Intensity         (picker)
4. What Matters      (text-prompt)

─────────────────────────────────────
PHASE 2: PROCESS (3 steps)
─────────────────────────────────────
5. Emotions          (picker)
6. Body Sensations   (picker)
7. Thoughts          (text-prompt)

─────────────────────────────────────
PHASE 3: ANCHOR (3 steps)
─────────────────────────────────────
8. Breathing         (breathing-exercise)
9. Scripture         (scripture-selection) *
10. Paraphrase       (text-prompt)

─────────────────────────────────────
PHASE 4: RESPOND (2 steps)
─────────────────────────────────────
11. Prayer           (text-prompt) **
12. Action Step      (text-prompt)

─────────────────────────────────────
PHASE 5: CLOSE (1 step)
─────────────────────────────────────
13. Summary          (summary) ***
  ↓
Complete → Saves to Supabase
          Returns to JournalHome

* AI Scripture suggestions (Phase 4 - deferred)
** AI Prayer generation (Phase 4 - deferred)
*** AI Summary (Phase 4 - deferred)

Session Persistence

Flow Engine → TemplateManager
                    ↓
         ┌──────────┴──────────┐
         │                     │
         ▼                     ▼
   AsyncStorage         Supabase
   (Auto-save)     (On Complete)
   
   • Draft saved every step
   • Final save includes:
     - userId
     - orgId (RLS)
     - All responses
     - Timestamps

Flow Engine Templates

Available Templates

Template ID	Name	Steps	Duration	Category
`sanctiv-journal-v1`	Sanctiv Journal	13	~12 min	Spiritual Growth
`quick-gratitude-v1`	Quick Gratitude	3	~2 min	Gratitude
`prayer-focus-v1`	Prayer Focus	3	~5 min	Prayer
`win-tracker-v1`	Win Tracker	4	~3 min	Coaching

Template Structure

JournalTemplate
├─ id: string
├─ name: string
├─ description: string
├─ category: string
├─ estimatedMinutes: number
└─ phases: Phase[]
    └─ Phase
        ├─ id: string
        ├─ title: string
        └─ steps: TemplateStep[]
            └─ TemplateStep
                ├─ id: string
                ├─ type: ContentType
                ├─ title: string
                ├─ prompt: string
                └─ config: StepConfig

Companions Flow

Companions Stack Structure

CompanionsStack
│
├─ CompanionsHome (Main Screen)
│  └─ Header: "Companions" + UserProfileHeader
│
├─ AddCompanion (modal)
│  └─ Create new companion
│
├─ CompanionProfile (modal)
│  └─ View/edit companion details
│
└─ Chat (fullScreen)
   └─ 1:1 conversation with companion

User Journey: Companion Interaction

┌────────────────┐
│ CompanionsHome │
└───────┬────────┘
        │
        ├─ "Add Companion" button
        │  └─→ AddCompanion (modal)
        │
        ├─ Tap companion card
        │  └─→ CompanionProfile (modal)
        │        │
        │        ├─ "Start Conversation"
        │        │  └─→ Chat screen
        │        │
        │        └─ View stats, insights, settings
        │
        └─ Tap "Message" on card
           └─→ Chat screen directly

Goals & Progress

Simple Stack Structures

Goals Stack

GoalsStack
│
└─ GoalsHome
   └─ Header: "Goals" + UserProfileHeader

Progress Stack

ProgressStack
│
└─ ProgressHome
   └─ Header: "Progress" + UserProfileHeader

Note: These are placeholder screens for future implementation

Settings & Profile

Global Modals (Available from any tab)

Any Screen (via UserProfileHeader)
      │
      ├─ Tap profile avatar
      │  └─→ Profile (modal)
      │
      └─ Tap settings icon
         └─→ Settings (modal)
              │
              ├─ Account settings
              ├─ Notifications
              ├─ Privacy
              └─ Sign Out
                 └─→ Login screen

Complete User Journey Map

New User (Full Journey)

1. App Launch
   └─→ Login

2. First Login
   └─→ Welcome Screen (3s)
       └─→ Main Tabs (Journal tab)

3. Empty State
   └─→ "Begin Your Journey"
       └─→ "Start Writing" button
           └─→ GuidedJournal Intro

4. Choose Path
   ├─→ "Start Guided Session" (13 steps)
   │   └─→ Complete → Saves to DB
   │       └─→ Back to JournalHome (now with entries)
   │
   └─→ "Start with Blank Page"
       └─→ WriteJournal
           └─→ Save → Back to JournalHome

Returning User (Typical Session)

1. App Launch
   └─→ Login
       └─→ Main Tabs (Journal tab)

2. JournalHome (with entries)
   └─→ Tap + button
       └─→ GuidedJournal Intro
           ├─→ Choose Guided (13 steps)
           └─→ Choose Blank Page

3. Browse past entries
   └─→ Tap entry card
       └─→ EntryDetail
           └─→ View content, AI insights

Maximum Depth by Tab

Tab	Max Depth	Example Path
Journal	3 levels	Journal → Guided Intro → Step 1-13 → Complete
Journal (Alt)	2 levels	Journal → WriteJournal → Save
Companions	3 levels	Companions → CompanionProfile → Chat
Goals	1 level	Goals (single screen)
Progress	1 level	Progress (single screen)

Global Modals (Overlay)

Settings (any tab)
Profile (any tab)

Deep Linking (Future)

Structure ready for deep links:

sanctiv://journal/entry/:entryId
sanctiv://companions/chat/:companionId
sanctiv://guided-session/:templateId

Technical Details

expo-router - File-based routing (built on React Navigation)
Hooks: useRouter, useLocalSearchParams, useFocusEffect, usePathname

Presentation Modes

Screen	Mode	Behavior
guided-journal	`fullScreenModal`	Full screen, slide up
companions/add	`modal`	Card modal (iOS)
companions/[id]	`modal`	Card modal (iOS)
profile	`modal`	Card modal (iOS)

State Management

Auth State: Zustand (authStore)
Journal State: Zustand (journalStore)
Flow Engine State: React Context (FlowContext)
Navigation State: Expo Router built-in

Key Files

File	Purpose
`src/navigation/AppNavigator.tsx`	Main navigation container
`src/flow-engine/FlowContainer.tsx`	Flow engine orchestrator
`src/flow-engine/FlowContext.tsx`	Flow session state
`src/templates/index.ts`	Template registry
`src/screens/GuidedJournalTestScreen.tsx`	Entry point for guided flow

Future Enhancements

Deep Linking - Direct links to specific entries/sessions
Tab Badge Counts - Unread companion messages
Onboarding Flow - First-time setup wizard
Template Selection - Choose from multiple templates
History/Drafts - Resume incomplete sessions

Debugging Tips

// In AppNavigator.tsx
<NavigationContainer
  onStateChange={(state) => {
    console.log('Navigation State:', state);
  }}
>

Check Current Route

import { usePathname, useSegments } from 'expo-router';

const pathname = usePathname();
const segments = useSegments();
console.log('Current Path:', pathname);
console.log('Segments:', segments);

Test Flow Engine State

// In any flow step
const { session, currentStepNumber, totalSteps } = useFlow();
console.log(`Step ${currentStepNumber}/${totalSteps}`, session);

Last Updated: November 20, 2025
Flow Engine Version: 1.0.0
Templates: 4 (1 main + 3 quick)

Development

Infrastructure

Integrations

Reference

​Sanctiv App - Navigation Flow Map

​Table of Contents

​Authentication Flows

​Unauthenticated Users

​First-Time Users (Authenticated)

​Returning Users

​Main App Structure

​Bottom Tab Navigation (4 Tabs)

​Journal Flow

​Journal Stack Structure

​User Journey: Creating a Journal Entry

​WriteJournal Screen (Blank Page)

​Guided Journal Flow Engine

​Flow Container Architecture

​Guided Session Flow (13 Steps)

​Session Persistence

​Flow Engine Templates

​Available Templates

​Template Structure

​Companions Flow

​Companions Stack Structure

​User Journey: Companion Interaction

​Goals & Progress

​Simple Stack Structures

​Goals Stack

​Progress Stack

​Settings & Profile

​Global Modals (Available from any tab)

​Complete User Journey Map

​New User (Full Journey)

​Returning User (Typical Session)

​Navigation Stack Depth

​Maximum Depth by Tab

​Global Modals (Overlay)

​Deep Linking (Future)

​Technical Details

​Navigation Libraries

​Presentation Modes

​State Management

​Key Files

​Future Enhancements

​Planned Navigation Features

​Debugging Tips

​View Navigation State

​Check Current Route

​Test Flow Engine State

Sanctiv App - Navigation Flow Map

Table of Contents