# User Journeys - Prophet-Priest-King

This document describes the complete user journeys for all personas in the Prophet-Priest-King application. These journeys serve as both documentation and the source of truth for end-to-end testing.

---

## Overview

The Prophet-Priest-King application supports **three distinct user personas**, each with their own journey through the application:

### 👤 Personal Survey User
**Who**: Individual users taking the assessment for personal spiritual leadership development

**Key Characteristics**:
- Not part of any organization
- Has only a personal survey
- Cannot view organization features
- Can delete own survey anytime

---

### 🏛️ Organization Member
**Who**: Users who belong to a church or ministry organization and participate in team assessments

**Key Characteristics**:
- Member of one organization
- Can take organizational surveys
- Can view organization dashboard and statistics
- Can invite other members (if allowed)
- Has equal permissions with other members
- Can switch between personal and organizational survey contexts

---

### 🔑 Super Administrator
**Who**: System administrators with elevated privileges across the entire application

**Key Characteristics**:
- Has `isAdmin` flag in Firebase
- Can view all organizations
- Can delete any user account (except own)
- Can delete organizations
- Can move personal surveys to organizations
- Cannot delete sole administrators of organizations

---

## Journey 1: Personal Survey User

### Step 1: User Sign-Up

**Goal**: Create a new account to access the leadership assessment

**Actions**:
1. Navigate to authentication page
2. Click 'Sign Up' tab or button
3. Enter first name, last name, email address, and password
4. Click 'Sign Up' button

**Expected Outcome**: User is authenticated and redirected to home page

**Validations**:
- ✓ User is redirected to /home route
- ✓ Navigation bar shows user is authenticated
- ✓ No error messages are displayed

---

### Step 2: User Sign-In

**Goal**: Access the application with existing account

**Actions**:
1. Navigate to authentication page
2. Ensure 'Sign In' tab is active
3. Enter email address and password
4. Click 'Sign In' button

**Expected Outcome**: User is authenticated and redirected to home page

**Validations**:
- ✓ User is redirected to /home route
- ✓ Navigation bar shows user is authenticated
- ✓ User's name is displayed in navigation

---

### Step 3: Create Personal Survey

**Goal**: Complete the Prophet-Priest-King leadership assessment to discover biblical leadership profile

**Actions**:
1. Navigate to Survey page from home
2. Verify survey context is 'Personal Survey'
3. Click 'Start Survey' button
4. Answer all 30 survey questions (10 per category: Prophet, Priest, King)
5. Submit the survey
6. View results page with calculated scores

**Expected Outcome**: Survey is saved, results are displayed, and biblical leadership profile is calculated

**Validations**:
- ✓ Survey results are displayed on screen
- ✓ Prophet, Priest, and King scores are shown
- ✓ Scores match expected profile
- ✓ Results page shows 'Edit Survey' and 'Retake Survey' buttons
- ✓ Survey is not linked to any organization

---

### Step 4: View Biblical Leadership Profile

**Goal**: Review my biblical leadership profile and scores

**Actions**:
1. Navigate to Profile page from navigation menu
2. View biblical leadership profile section
3. Review Prophet, Priest, and King scores
4. Read profile interpretation

**Expected Outcome**: Profile displays current biblical leadership assessment results

**Validations**:
- ✓ Profile page loads successfully
- ✓ Biblical leadership scores are displayed
- ✓ Profile matches survey results
- ✓ User information is displayed correctly

---

### Step 5: Edit Survey

**Goal**: Update survey answers to better reflect current leadership style

**Actions**:
1. Navigate to Survey page
2. Click 'Edit Survey' button
3. Modify responses to survey questions
4. Submit the updated survey
5. View updated results

**Expected Outcome**: Survey responses are updated, new results are calculated and displayed

**Validations**:
- ✓ Updated survey results are displayed
- ✓ Scores reflect the modified answers
- ✓ New profile is shown
- ✓ Profile page reflects the updated results

---

### Step 6: Retake Survey

**Goal**: Retake the assessment to see how leadership style has evolved

**Actions**:
1. Navigate to Survey page
2. Click 'Retake Survey' button
3. Answer all 30 survey questions with new responses
4. Submit the new survey
5. View new results

**Expected Outcome**: New survey replaces old one, fresh results are calculated and displayed

**Validations**:
- ✓ New survey results are displayed
- ✓ Scores reflect the retake responses
- ✓ New profile is shown
- ✓ Profile page reflects the latest results
- ✓ Previous survey data is replaced (not duplicated)

---

### Step 7: Verify Profile Updates

**Goal**: Ensure profile reflects most recent assessment

**Actions**:
1. Navigate to Profile page
2. Verify biblical leadership profile displays latest scores
3. Confirm profile interpretation matches current assessment

**Expected Outcome**: Profile shows most recent survey results with correct biblical leadership profile

**Validations**:
- ✓ Profile displays valid scores for all three categories
- ✓ Scores are greater than zero
- ✓ Profile matches the latest survey results
- ✓ All profile updates throughout journey are distinct and correct

---

### Step 8: User Sign-Out

**Goal**: Safely log out and end session

**Actions**:
1. Click user menu or sign-out button in navigation
2. Click 'Sign Out' option
3. Confirm sign-out if prompted

**Expected Outcome**: User is signed out and redirected to authentication page

**Validations**:
- ✓ User is redirected to authentication page
- ✓ Navigation shows unauthenticated state
- ✓ Protected routes are no longer accessible

---

## Journey 2: Organization Member

### Step 1: Sign-Up or Sign-In

**Goal**: Access the application to join an organization

**Actions**:
1. Complete sign-up or sign-in process (same as personal user)

**Expected Outcome**: User is authenticated and on home page

**Validations**:
- ✓ User is authenticated
- ✓ Home page loads successfully

---

### Step 2: Join Organization

**Goal**: Become a member of church or ministry organization

**Actions**:
1. Receive invitation link or code from organization member
2. Click invitation link OR navigate to Organizations and enter code
3. Review organization details on join page
4. Click 'Join Organization' button
5. Wait for confirmation message

**Expected Outcome**: User becomes member of organization and is redirected to organization dashboard

**Validations**:
- ✓ User is added to organization memberships
- ✓ Organization member count increments
- ✓ Success message displays
- ✓ User is redirected to organization dashboard
- ✓ Survey context switches to organization

---

### Step 3: View Organization Dashboard

**Goal**: See team survey statistics and understand collective leadership profile

**Actions**:
1. Click 'Organizations' card on home page
2. System auto-navigates to organization dashboard (user has only 1 org)
3. Review organization information
4. View aggregate survey statistics (if surveys exist)
5. Review member list
6. Explore dashboard features

**Expected Outcome**: Dashboard displays with organization data and available actions

**Validations**:
- ✓ Organization name and description display
- ✓ Member list shows all members
- ✓ Action buttons are visible (Take Survey, View Matrix, etc.)
- ✓ If surveys exist, statistics are shown
- ✓ User can see invitation link/code

---

### Step 4: Take Organizational Survey

**Goal**: Complete assessment as part of organization's team evaluation

**Actions**:
1. Verify survey context is set to organization
2. Navigate to Survey page
3. Click 'Start Survey' button
4. Answer all 30 survey questions
5. Submit the survey
6. View results

**Expected Outcome**: Survey is saved with organizationId, results displayed, organization statistics updated

**Validations**:
- ✓ Survey is linked to organization
- ✓ Results display correctly
- ✓ Organization dashboard statistics update
- ✓ User appears in organization survey matrix (if viewed)

---

### Step 5: View Survey Response Matrix

**Goal**: See how all team members answered each question

**Actions**:
1. Navigate to organization dashboard
2. Click 'View Survey Matrix' button
3. Matrix expands showing all questions and member responses
4. Scroll horizontally to view all members
5. Review star ratings for each question
6. Click 'Hide Survey Matrix' to collapse

**Expected Outcome**: Matrix displays with all questions and member responses in star format

**Validations**:
- ✓ Matrix shows all 30 questions organized by category
- ✓ Member names appear as column headers
- ✓ Responses display as star ratings (1-5 stars)
- ✓ Members without surveys show placeholders
- ✓ Question column remains fixed during horizontal scroll

---

### Step 6: Compare Team Members

**Goal**: Understand how team members complement each other

**Actions**:
1. Select 2-5 members using checkboxes on member cards or matrix
2. Selected members highlight with blue border
3. Click 'Compare Selected' button
4. Review comparison dialog showing:
   - Team member overview with scores
   - Team balance analysis
   - Complementary strengths
   - Potential friction points
   - Growth opportunities
   - Biblical reflection
5. Click 'Close' to return to dashboard

**Expected Outcome**: Comparison insights display with actionable team dynamics analysis

**Validations**:
- ✓ Comparison dialog opens
- ✓ All selected members' scores display
- ✓ Team balance score calculated
- ✓ Complementary strengths identified
- ✓ Recommendations provided
- ✓ Biblical references included

---

### Step 7: View Another Member's Survey

**Goal**: See detailed responses from a specific team member

**Actions**:
1. Navigate to organization dashboard
2. Find member in members list
3. Click 'View Survey' button for that member
4. Full survey results page loads
5. Review member's survey details
6. Use browser back to return to dashboard

**Expected Outcome**: Member's survey displays in read-only mode

**Validations**:
- ✓ Survey page loads for selected member
- ✓ Page is read-only (no edit/retake buttons)
- ✓ All survey details visible
- ✓ Print option available
- ✓ Back button returns to dashboard

---

### Step 8: Invite New Members

**Goal**: Invite others from church to join organization

**Actions**:
1. Navigate to organization dashboard
2. Click 'Invite Members' button
3. View invitation link and code
4. Click 'Copy Link' button
5. Share link via email or messaging

**Expected Outcome**: Invitation link copied to clipboard for sharing

**Validations**:
- ✓ Invitation panel displays
- ✓ Link format is correct
- ✓ Code is displayed
- ✓ Copy confirmation message shows
- ✓ Link can be shared externally

---

### Step 9: Edit Organization Settings

**Goal**: Update organization's name or settings

**Actions**:
1. Navigate to organization dashboard
2. Click 'Edit Settings' button
3. Modify organization name, description, or settings
4. Click 'Update Organization' button
5. View success confirmation

**Expected Outcome**: Organization settings are updated successfully

**Validations**:
- ✓ Settings form displays with current values
- ✓ Changes save successfully
- ✓ Dashboard reflects updates
- ✓ Success message displays

---

### Step 10: Switch Survey Context

**Goal**: Take a personal survey separate from organizational survey

**Actions**:
1. Click profile dropdown in navigation
2. View 'Survey Context' section
3. See available contexts: Personal (👤) and Organization (🏛️)
4. Click desired context
5. Context updates
6. Take survey in selected context

**Expected Outcome**: Survey context switches, allowing separate surveys in different contexts

**Validations**:
- ✓ Context selector displays available options
- ✓ Selected context updates
- ✓ Survey page reflects current context
- ✓ Separate surveys can exist in each context
- ✓ User cannot have duplicate surveys in same context

---

## Journey 3: Super Administrator

### Step 1: Super Admin Sign-In

**Goal**: Access administrative functions

**Actions**:
1. Sign in with admin-flagged account
2. Verify `isAdmin` flag is set in userProfiles Firestore document

**Expected Outcome**: Admin is authenticated with elevated permissions

**Validations**:
- ✓ User is authenticated
- ✓ Admin flag is present
- ✓ Additional admin features visible

---

### Step 2: View All Organizations

**Goal**: See and manage all organizations in the system

**Actions**:
1. Click 'Organizations' card on home page
2. System detects admin flag and navigates to /organizations
3. View list of ALL organizations
4. See 'Super Admin View' badge
5. Review organization details and member counts

**Expected Outcome**: Admin sees complete list of all organizations in system

**Validations**:
- ✓ Admin is routed to /organizations (not individual org)
- ✓ All organizations display in list
- ✓ Super admin badge is visible
- ✓ Each organization shows member count and status
- ✓ Admin can access any organization

---

### Step 3: Access Member Management

**Goal**: View and manage members across organizations

**Actions**:
1. Navigate to organization dashboard
2. Click 'Manage Members' button
3. View complete member list with admin controls
4. See 'Delete Account' buttons (super-admin only)

**Expected Outcome**: Admin sees member management with elevated controls

**Validations**:
- ✓ Member list displays all members
- ✓ 'Delete Account' buttons visible (except for admin's own account)
- ✓ Admin can perform member operations
- ✓ Standard 'Remove' buttons also visible

---

### Step 4: Delete User Account

**Goal**: Remove a user account from the system completely

**Actions**:
1. View member management page
2. Click 'Delete Account' button for target user
3. System loads deletion summary showing:
   - User name and email
   - Number of surveys
   - Organization memberships
   - Admin roles in organizations
4. **If user is last admin in any org**:
   - Error displays, deletion blocked
   - Admin must assign another admin first
5. **If no blockers**:
   - Type user's email address exactly
   - Click 'DELETE ACCOUNT PERMANENTLY' button
   - Confirm deletion
6. System deletes all user data:
   - All surveys (all contexts)
   - User survey index
   - Organization memberships
   - User profile
   - Updates organization member counts
7. Success message displays
8. Member list refreshes

**Expected Outcome**: User account and all associated data permanently deleted

**Validations**:
- ✓ Deletion summary loads correctly
- ✓ Last admin blocker prevents deletion if applicable
- ✓ Email confirmation required
- ✓ Delete button disabled until email matches
- ✓ All user data removed from Firestore
- ✓ Organization member counts updated
- ✓ Success message displays
- ✓ Member list refreshes without deleted user
- ✓ Firebase Auth account remains (manual deletion needed)

---

### Step 5: Delete Organization

**Goal**: Remove an inactive or problematic organization

**Actions**:
1. Navigate to organization dashboard or list
2. Click 'Delete Organization' button (super-admin only)
3. Review deletion confirmation
4. Confirm deletion
5. System removes organization and all memberships

**Expected Outcome**: Organization and all memberships deleted

**Validations**:
- ✓ Delete button only visible to super-admins
- ✓ Confirmation dialog displays
- ✓ Organization deleted from database
- ✓ All memberships removed
- ✓ Organization no longer appears in lists

---

### Step 6: Move Personal Survey to Organization

**Goal**: Help users transition personal surveys to organizational context

**Actions**:
1. Navigate to admin features or user management
2. Select user with personal survey
3. Choose target organization
4. Click 'Move Survey' button
5. Confirm move operation
6. Survey is reassigned to organization context

**Expected Outcome**: Personal survey becomes organizational survey

**Validations**:
- ✓ Survey `organizationId` field updates
- ✓ Survey no longer appears as personal
- ✓ Survey appears in organization dashboard
- ✓ Organization statistics include moved survey
- ✓ User can view survey in organizational context

---

### Step 7: View All Personal Surveys

**Goal**: Monitor personal survey usage and identify surveys for potential organizational migration

**Actions**:
1. Navigate to admin dashboard or surveys section
2. Filter to show only personal surveys (organizationId null or empty)
3. View list with user information
4. Identify surveys that could be moved to organizations

**Expected Outcome**: Complete list of all personal surveys in system

**Validations**:
- ✓ Only personal surveys display
- ✓ User information shown for each survey
- ✓ Survey details accessible
- ✓ Move to organization option available

---

### Step 8: Monitor System Health

**Goal**: Ensure the application is functioning properly

**Actions**:
1. View admin dashboard
2. Review system statistics:
   - Total users
   - Total organizations
   - Total surveys (personal and organizational)
   - Active users
3. Monitor for issues or anomalies

**Expected Outcome**: System health data visible to admin

**Validations**:
- ✓ All metrics display correctly
- ✓ Data is current
- ✓ No system errors visible

---

## Business Rules

### Survey Management
- **One Survey Per Context**: Each user can have only one survey per context (personal OR organizational)
- **Survey Scoring**: 30 questions total: 10 Prophet, 10 Priest, 10 King. Each rated 1-5. Maximum score per category: 50
- **Profile Calculation**: Biblical leadership profile is determined by the highest score among Prophet, Priest, and King categories

### Organization Management
- **Single Organization**: Users can belong to only ONE organization at a time
- **Equal Permissions**: All organization members have equal permissions (no admin/moderator roles within organizations)
- **Invitation Codes**: Unique 8-character codes that are permanent

### Administration
- **Super Admin Flag**: Set manually in Firebase (`isAdmin: true` in userProfiles)
- **Self-Protection**: Admins cannot delete their own accounts
- **Last Admin Protection**: Cannot delete users who are sole administrators of any organization
- **Permanent Deletion**: All user data deletions are permanent with no recovery option

---

## Test Configuration

### Environment
- **Testing Environment**: Firebase Emulators (Auth, Firestore, UI)
- **Application URL**: http://localhost:4200
- **Test Framework**: Playwright
- **Browser Support**: Chromium, Firefox, WebKit

### Emulator Ports
- **Auth Emulator**: 9099
- **Firestore Emulator**: 8080
- **Emulator UI**: 4000

---

## Data Model

### User Profile
```typescript
{
  firstName: string;
  lastName: string;
  email: string;
  isAdmin?: boolean;  // Super admin flag
  biblicalLeadershipProfile: "Prophet" | "Priest" | "King" | "Balanced";
  scores: {
    prophet: number;  // 0-50
    priest: number;   // 0-50
    king: number;     // 0-50
  }
}
```

### Survey
```typescript
{
  userId: string;
  organizationId?: string;  // null/empty for personal surveys
  questions: number[];      // Array of 30 responses (1-5 rating)
  createdAt: Timestamp;
  updatedAt: Timestamp;
  scores: {
    prophet: number;
    priest: number;
    king: number;
  }
}
```

### Organization
```typescript
{
  id: string;
  name: string;
  description?: string;
  memberCount: number;
  isActive: boolean;
  invitationCode: string;   // 8-character unique code
  createdAt: Timestamp;
  updatedAt: Timestamp;
  settings: {
    allowMemberInvites: boolean;
    surveyVisibility: "private" | "members" | "public";
  }
}
```

---

## Related Documentation

- [SDLC Workflow](https://Notarangelo-Technical-Advisory.github.io/Prophet-Priest-King/) - Visual development lifecycle
- [E2E Testing Guide](../E2E_TESTING_GUIDE.md) - Automated testing documentation
- [Requirements: Organizations](../Requirements/Organizations.md) - Organization feature requirements
- [Requirements: Admin Features](../Requirements/AdminFeatures.md) - Super admin capabilities
- [Requirements: Survey Management](../Requirements/SurveyManagement.md) - Survey functionality

---

**Version**: 2.0.0  
**Last Updated**: November 22, 2025  
**JSON Data Source**: [user-journey.json](./user-journey.json)