🗺️ User Journeys

Complete workflows for all personas in the Solomon application

🏠 Home 🏗️ Architecture 📖 Framework ⚡ Quick Reference 🚀 SDLC

👥 User Personas

👤
Counselee
Individual users seeking biblical counseling through Solomon's AI
  • Creates individual or couples sessions
  • Chats with Solomon AI counselor
  • Configures personal profile & preferences
  • Requests connection to a human counselor
  • Uses voice readback (TTS)
🧑‍⚕️
Counselor
Professional biblical counselors who oversee counselee sessions
  • Views assigned counselee sessions (read-only)
  • Writes encrypted annotations on AI messages
  • Sends direct messages to counselees
  • Seeds guided prompts for session openers
  • Manages Stripe subscription
🔑
Administrator
System administrators with elevated privileges
  • Manages all user accounts and roles
  • Views system-wide user list
  • Approves counselor applications

🔐 Authentication Flow

1

Sign Up / Sign In

User navigates to /auth and creates an account or signs in with existing credentials. On successful authentication, redirected to /dashboard.

2

Terms Gate

First-time users must accept terms at /terms before accessing the dashboard.

3

Profile Setup

User completes their profile at /profile — church role, denomination, age, marital status, years in faith, spiritual disciplines, prayer preference, counseling goals, theological influences, and TTS voice preference.

👤 Individual Counseling Journey

1

Create Session

From /dashboard, user clicks to create a new session. On /session/new, chooses Individual mode. System generates a session ID and per-session AES-256-GCM encryption key.

2

Chat with Solomon

At /session/:id, user engages in conversation with Solomon AI. All messages are encrypted before writing to Firestore. Solomon responds with Reformed biblical counsel, one open-ended question per response.

3

Voice Readback (Optional)

If ttsEnabled: true in profile, a speaker button appears on each AI message bubble. Clicking it streams ElevenLabs TTS via the synthesizeSpeech Cloud Function. Four voices available: female/male American and British. Audio is cached client-side per message so replaying the same message does not make additional ElevenLabs requests. If the ElevenLabs usage limit is reached, a dismissible error banner is shown in the chat input area.

4

Close Session

User closes the session, triggering an AI-generated summary. Session becomes read-only. Summary and transcript available at /session/:id/summary.

Outcome: User receives personalized biblical counsel, all messages encrypted at rest, with optional voice readback (with client-side audio caching for replays) and a session summary for future reference.

💑 Couples Counseling Journey

1

Create Couples Session

Creator selects Couples mode on /session/new and enters their partner's email address. System creates the session and generates an invite token (7-day expiry).

2

Partner Invitation

Partner receives an email with a link to /invite/:token. If they already have an account, they click Accept. If new, they sign up and auto-join the session.

3

Joint Counseling

Both participants chat with Solomon. Messages are labeled with each partner's name ([Name]: prefix). Solomon maintains strict impartiality, pursuing mutual responsibility and genuine reconciliation.

Note: Both users must have Solomon accounts. The invite flow handles both existing users (Accept button) and new signups (registration + auto-join).

🧑‍⚕️ Counselor Journey

1

Counselor Dashboard

At /counselor, the counselor views assigned counselees and manages their subscription status.

2

Session Review

At /counselor/session/:id, the counselor sees a read-only tab view of the counselee's AI conversation, plus a direct messaging tab and an annotation tab.

3

Annotations & Guided Prompts

Annotations: Pastoral notes threaded on specific AI messages, encrypted, and injected into Solomon's context on the next user message. Guided Prompts: Counselor seeds prompt cards that appear for the counselee at session open.

🔊 Voice & TTS Features

🔊

Per-Message Readback

A speaker button on each AI message bubble (visible only when ttsEnabled: true in user profile). Uses ElevenLabs streaming via the synthesizeSpeech Cloud Function.

Available Voices

  • Juliet — Female American
  • Josh — Male American
  • Maisie — Female British
  • Daniel — Male British

Technical: Sentence splitting with a rolling prefetch window (2 sentences ahead). iOS uses a persistent <video> element with play-unlock on user gesture. Audio blobs are cached client-side keyed by messageId|voice — replaying the same message reuses cached audio without additional ElevenLabs API calls.

Error handling: If ElevenLabs returns a quota_exceeded error, the synthesizeSpeech function returns a structured JSON error ({ error, reason: "quota_exceeded" }). The client (TtsService) detects this, sets a ttsError signal, and displays a dismissible banner in the chat UI explaining that voice readback is temporarily unavailable.

🗺️ Route Map

Route Component Access
/auth AuthComponent Public
/terms TermsComponent Public
/invite/:token CoupleInviteComponent Public
/dashboard DashboardComponent Auth
/profile ProfileComponent Auth
/session/new NewSessionComponent Auth
/session/:id ChatComponent Auth
/session/:id/summary SessionSummaryComponent Auth
/counselor CounselorDashboardComponent Counselor
/counselor/profile CounselorProfileComponent Counselor
/counselor/pricing CounselorPricingComponent Counselor
/counselor/session/:id ChatComponent Counselor
/admin/users UserListComponent Admin

🔒 Session Lifecycle

Create

SessionService.createSession() generates a session ID and a per-session AES-256-GCM encryption key stored in sessionKeys.

Active

User/couple chats with Solomon. Every message is encrypted before Firestore write. Counselor can view, annotate, and send direct messages.

Close

SessionService.closeSession() generates an AI summary, locks the session to read-only.

Delete

Only the session creator can delete. Removes all chatMessages and the session encryption key. Permanent, no recovery.

↑