Individual User Story

End-to-end journey for the Individual role (health consumer) in Syntropy Health. Covers onboarding through every sidebar feature, ambient AI, and external integrations (Slack, MCP, API).

1. Onboarding Flow

1.1 Discovery

Step	What Happens	Route	Auth
Visit landing page	Public page with ShrineAI chat widget	`/`	None
Explore public pages	About, Connect, Startup, Partnership, Dietary Science, Privacy, Terms, Slides	`/about`, `/connect`, etc.	None
Browse product catalog	Public protocol/product listing	`/products`	None
View protocol detail	Protocol info with “Adopt” CTA (prompts sign-in)	`/lounge/protocol/[id]`	None

Step	What Happens	Route	Implementation
Click Sign In	Clerk-hosted sign-in component (email + Google SSO)	`/sign-in`	`auth_page_wrapper`
SSO callback	OAuth redirect processing	`/sign-in/sso-callback`	`SSOAuthState.handle_sso_callback`
Auth sync	Clerk identity synced to auth state (no local User model)	—	`AuthState.sync_auth_state`
Referral tracking	`ref` cookie → Clerk `private_metadata.referral` (new users only)	—	`AuthState.handle_referral_cookie`
Onboarding check	If `user.onboarding_completed == False`, show onboarding wizard	—	`AuthState.check_onboarding`
Role redirect	Individual → `/shrine/dashboard`	—	`PageAuthState.redirect_by_role`
Dashboard loads	HealthDM tabbed dashboard with stats, check-ins, protocols	`/shrine/dashboard`	`CheckinState.on_load`

Auth guard chain (every protected page):

clerk.on_load() → AuthState.sync_auth_state → PageAuthState.ensure_authenticated → [page on_load]

1.3 Demo Onboarding (First-Time Wizard)

New users who haven’t completed onboarding are presented a 3-step wizard modal:

Step	What Happens	Implementation
1. Welcome	Role confirmation (individual vs partner) + platform overview	Modal step 1
2. Demo data opt-in	”Try with demo data?” toggle — if yes, inject seed data into state vars (NOT into DB)	`AuthState.is_demo_mode = True`
3. Feature tour	Highlight sidebar items: HealthDM, Lounge, Chat widget	Guided tour overlay
Complete	Set `user.onboarding_completed = True` in DB + Clerk metadata	`AuthState.complete_onboarding()`

Demo mode behavior:

State vars load from data/seed/ constants instead of DB
Clear visual indicator: “Demo Mode” badge in navbar
Real user data is never mixed with demo data
Exit demo: Clear demo state vars → user sees their real (empty) data
Re-enter demo: /shrine/help page has “Start onboarding tour” button

The sidebar has two switchable sections: The Shrine (personal health) and The Lounge (protocol adherence & feedback).

The Shrine Section

Sidebar Link	Route	What It Does
HealthDM	`/shrine/dashboard`	Main dashboard: stats, check-ins, protocols, food/supplement tracking
Message Center	`/shrine/notifications`	Health insights, DIET alerts, protocol reminders (with unread badge)
Health Profile	`/shrine/profile`	Dietary prefs, supplements, goals, conditions, allergies, completeness %
Settings	`/shrine/settings`	Order integrations, notifications, data sharing, API tokens, subscription
Help	`/shrine/help`	Platform help, re-trigger onboarding tour, demo mode toggle

The Lounge Section

Sidebar Link	Route	What It Does
My Lounge	`/lounge`	Subscribed protocols grid, protocol selector, adherence timeline, notes feed
Catalog	`/lounge/catalog`	Browse marketplace, subscribe/unsubscribe, compatibility scoring

ShrineAI is not a sidebar link — it’s a floating chat widget available on every authenticated page.

Element	Behavior
Trigger	Teal floating button, bottom-right corner
Collapsed	Icon only, subtle pulse when AI has a suggestion
Expanded	Slide-up chat panel with message input, voice button, streaming responses
Minimized	Last message preview bar (click to expand)
Persistence	Single session — messages persist across page navigation via Reflex state
Context	Injected: last 3 message pairs from DB, current page context

Chat modes: LANDING (anonymous, on public pages), SHRINE (full auth, on protected pages) LLM fallback chain: OpenRouter free models → Cerebras Llama 3.3

Route	Page Title	Access
`/lounge/protocols`	My Protocols	”View All” link from dashboard protocols section
`/shrine/subscription`	Subscription	Plan selection + Stripe checkout

Backward Compatibility Redirects

Old Route	New Route	Status
`/shrine-checkin`	`/shrine/dashboard`	301
`/longevitian`	`/shrine/dashboard`	301
`/longevitian/shrine-chat`	removed (chat widget)	301 → `/shrine/dashboard`
`/notifications`	`/shrine/notifications`	301
`/profile`	`/shrine/profile`	301
`/settings`	`/shrine/settings`	301
`/catalog`	`/lounge/catalog`	301
`/my-protocols`	`/lounge/protocols`	301
`/lounge`	`/lounge`	unchanged

3. Feature Walkthrough

3.1 HealthDM Dashboard (`/shrine/dashboard`)

Tabbed interface:

Tab	Content	Status
Overview	5 stat cards (total, this week, voice, text, phone) + check-in list + My Protocols	Built
Food Tracker	Food consumption tracking	Placeholder (“Coming soon”)
Medications	Medication tracking	Placeholder (“Coming soon”)
Conditions	Health conditions	Placeholder (“Coming soon”)
Symptoms	Symptom tracking	Placeholder (“Coming soon”)

Check-in flow:

Click “New Check-in” → modal with topic pills + textarea
Select input type (Text or Voice)
Toggle health domains (medication, diet, symptoms…)
Submit (min 3 chars) → create pending record
AI processing: LLM extracts medications, foods, symptoms
Health entries saved to DB (MedicationEntry, FoodLogEntry, SymptomEntry)
View in this-week / past sections with pagination (5/page)
Filter by status: All / Pending / Processed / Flagged
Click to view details, edit, or delete

Phone check-in sync (CDC pipeline):

Background loop (30s interval) fetches Bland.ai call transcripts
Auto-ingests as phone check-ins with LLM processing
“Sync Now” button for manual refresh

Single-session chat with LangGraph agent (no multi-session management)
Floating panel, bottom-right — expands on click, minimizes to icon
Streaming token-by-token rendering
Voice input via browser audio recording → transcription
Context injection: last 3 message pairs from DB + current page context
Tool usage indicator during agent operations
Available on every authenticated page via build_layout() injection

3.3 Protocol Marketplace & Subscriptions

The Lounge catalog (/lounge/catalog) is a marketplace where users discover health protocols matched to their profile. Protocols are sourced from the Shopify Protocols seller app and enriched with compatibility scoring. Discovery flow:

Step	What Happens	Route	Implementation
Browse catalog	Grid of protocol cards with compatibility scores, goal tags, and category badges	`/lounge/catalog`	`CatalogState.initialize_catalog`
View scoring	Each card shows 0-100 compatibility score (emerald/amber/slate/red tiers)	—	`_enrich_protocol_with_scoring()`
Subscribe	Click “Subscribe” button on any catalog card	—	`CatalogState.toggle_subscription`
View subscriptions	”My Subscriptions” section appears at top of Lounge dashboard	`/lounge`	`LoungeState.user_subscriptions`
Unsubscribe	Click “Unsubscribe” on subscription card in Lounge dashboard	—	`LoungeState.unsubscribe_protocol`

Marketplace scoring fields (from Shopify metafields):

Field	Description
`compatibility_score`	0-100 weighted composite (goal alignment 40%, gap filling 30%, community 10%, protocol quality 20%)
`confidence_tier`	HIGH / MEDIUM / LOW / INSUFFICIENT based on profile completeness + community data
`functional_goals`	Goal tags: cognitive, sleep, gut_health, etc.
`evidence_level`	clinical, peer_reviewed, anecdotal, etc.
`category_badge`	Nutraceutical category with color-coded badge

Subscription card (Lounge dashboard): Each subscribed protocol shows:

Adherence score circle (0-100 PDC with emerald/amber/rose tiers)
Current streak in days
Days active since subscription
Category badge + protocol image
Dosage, frequency, timing details
Unsubscribe action

3.4 Protocol Adoption & Adherence

Browse /lounge/catalog → view protocol detail → click “Adopt”
Set reminder time (HH:MM), toggle data sharing with partner
Daily check-in modal: taken/skipped + optional note
Dashboard “My Protocols” section shows progress, streak, adherence %
/lounge/protocols for full list; /lounge for timeline view
Pause/resume protocols, missed detection runs automatically

3.5 Health Profile (`/shrine/profile`)

7 sections: username, display name, bio, dietary preferences (toggle-based), supplement stack, health goals, conditions, allergies. Auto-calculated completeness %.

3.6 Settings (`/shrine/settings`)

6 collapsible sections:

Order Integrations — 8 partners, all “Coming soon”
Dietary Preference — toggle-based dietary selections
Notifications — frequency + aggressiveness sliders
Data Sharing & Privacy — per-protocol opt-in for partner visibility
Payment & Subscription — Stripe checkout, plan management
Admin Tokens — create named tokens, view active tokens, revoke, copy (see §3.8)

3.7 Notifications (`/shrine/notifications`)

4 types with 3-tier priority routing:

Type	Color	Priority	Delivery
ALERT	Red	High (DIET severity)	Immediate push + in-app + sound
SUGGESTION	Amber	Medium	In-app + daily digest push
TIPS	Blue	Low	In-app only
PROTOCOL_REMINDER	Teal	Medium	In-app + push at scheduled time

Collapsible sections, 10/page, mark as read, dismiss. Notification delivery channels:

In-app: Real-time via Reflex state (existing)
Web push: Service Worker + VAPID keys (requires browser permission)
Queue: Notifications flow through async queue (asyncio.Queue → NATS at scale)

3.8 Slack Integration (External)

Command	Auth	What It Does
`/syntropy-foodnews`	None	DuckDuckGo top 5 food safety news (ephemeral)
`/shrine-checkin TOKEN:<token> text`	Admin token	Creates health check-in via `process_with_llm()`
`/shrine-rate-diet TOKEN:<token>`	Admin token	30-day diet fulfillment score
DM / @mention bot	None	ShrineAI LANDING mode conversation

Token format: TOKEN:<token> — admin token generated via Settings UI. Legacy sh_* keys still accepted (deprecated, compat layer logs warning).

3.9 Admin Token Management

Users manage admin tokens from /shrine/settings → Admin Tokens section:

Action	What Happens
Create token	Name + expiration (30/90/365 days or never) → generates token, shown once
List tokens	Table: name, created date, expiration, status
Revoke token	Deactivate immediately, non-reversible
Copy token	One-click copy to clipboard (only on initial creation)

Admin tokens are internal, full-access tokens for authenticating the user’s own integrations. They are not scoped — any valid token grants full access to the user’s data. Dual token system:

Clerk-issued tokens (new) — split-token SHA-256 pattern via reflex-clerk-api, with expiration support
Legacy sh_* keys (deprecated) — still accepted via validate_token_compat middleware with deprecation warning

Tokens authenticate access to:

REST API (/api/ext/*) — health data CRUD, check-in submission, protocol queries
MCP Server — same capabilities via Model Context Protocol for AI tool integration
Slack bot — TOKEN:<token> prefix in slash commands

3.10 MCP Integration (Developer)

MCP-compatible AI tools (Claude Desktop, etc.) can connect to Syntropy Health using an admin token:

MCP Tool	Maps To
`get_profile`	User health profile
`create_checkin`	Log a health check-in
`list_protocols`	Adopted protocols
`get_adherence`	Protocol adherence stats
`search_catalog`	Browse protocol catalog
`get_notifications`	Recent notifications

See docs/integrations/mcp.md for setup instructions.

4. Demo Run (Individual)

Prerequisites

make setup              # Install deps + start PostgreSQL + run migrations
make run seed           # Seed demo data (creates user + API key)

Start the Server

make run dev            # Start with real Clerk auth
# Or: make run dev-mock  (mocked LLM + transcription, no API keys needed — auth is still real Clerk)

Individual Demo Walkthrough

Open http://localhost:3000/sign-in
Sign in with your Clerk dev account (the email in ADMIN_USER_EMAILS in envs/base)
Auth syncs to local DB → onboarding wizard appears (first time)
Complete wizard: confirm role → enable demo data → tour highlights
Redirects to /shrine/dashboard with demo data populated
Explore The Shrine sidebar:
- HealthDM — view demo check-ins, stats, browse tabs
- Message Center — view demo DIET alerts and protocol reminders
- Health Profile — see pre-filled dietary prefs, supplements, goals
- Settings — notification preferences, data sharing, API tokens
- Help — re-trigger onboarding, toggle demo mode
Switch to The Lounge section in sidebar dropdown:
- My Lounge — view demo protocol timeline + adherence
- Catalog — browse and adopt a protocol
Click the ShrineChat widget (bottom-right) to chat with AI assistant
Exit demo mode from Help page or navbar badge → see real (empty) data

Slack Demo

After make run dev with ngrok:

# Food news (no auth needed)
/syntropy-foodnews

# Health check-in (requires admin token from Settings)
/shrine-checkin TOKEN:<your_token> feeling great after a green smoothie

# Diet score (requires admin token)
/shrine-rate-diet TOKEN:<your_token>

Create an admin token from /shrine/settings → Admin Tokens section.

5. Page Wrapper Reference

Wrapper	Auth	Navbar	Sidebar	Chat Widget	Used By
`app_page_wrapper`	Yes	Yes	Yes	Yes	Dashboard, catalog, settings, profile, notifications, lounge, protocols, subscription, help
`auth_page_wrapper`	No	Yes	No	No	Sign-in, SSO callback
`standalone_page_wrapper`	No	Yes	No	No	Landing, about, products, protocol detail
`partner_page_wrapper`	Yes (partner)	Yes	Yes	Yes	Partner portal, onboarding

Note: chat_page_wrapper is removed — ShrineChat is now a floating widget injected by build_layout() in all authenticated wrappers.

Architecture

Development

Auth & Security

MCP (Model Context Protocol)

Operations

Design

User Stories

Individual User Story

Individual User Story

1. Onboarding Flow

1.1 Discovery

1.3 Demo Onboarding (First-Time Wizard)

2. Sidebar Navigation

The Shrine Section

The Lounge Section

Ambient ShrineChat Widget

Additional Protected Pages (not in sidebar)

Backward Compatibility Redirects

3. Feature Walkthrough

3.1 HealthDM Dashboard (`/shrine/dashboard`)

3.2 Ambient ShrineChat Widget (All Pages)

3.3 Protocol Marketplace & Subscriptions

3.4 Protocol Adoption & Adherence

3.5 Health Profile (`/shrine/profile`)

3.6 Settings (`/shrine/settings`)

3.7 Notifications (`/shrine/notifications`)

3.8 Slack Integration (External)

3.9 Admin Token Management

3.10 MCP Integration (Developer)

4. Demo Run (Individual)

Prerequisites

Start the Server

Individual Demo Walkthrough

Slack Demo

5. Page Wrapper Reference

6. State Dependencies

7. Route Map Summary

Architecture

Development

Auth & Security

MCP (Model Context Protocol)

Operations

Design

User Stories

​Individual User Story

​1. Onboarding Flow

​1.1 Discovery

​1.2 Sign-Up & First Login

​1.3 Demo Onboarding (First-Time Wizard)

​2. Sidebar Navigation

​The Shrine Section

​The Lounge Section

​Ambient ShrineChat Widget

​Additional Protected Pages (not in sidebar)

​Backward Compatibility Redirects

​3. Feature Walkthrough

​3.1 HealthDM Dashboard (/shrine/dashboard)

​3.2 Ambient ShrineChat Widget (All Pages)

​3.3 Protocol Marketplace & Subscriptions

​3.4 Protocol Adoption & Adherence

​3.5 Health Profile (/shrine/profile)

​3.6 Settings (/shrine/settings)

​3.7 Notifications (/shrine/notifications)

​3.8 Slack Integration (External)

​3.9 Admin Token Management

​3.10 MCP Integration (Developer)

​4. Demo Run (Individual)

​Prerequisites

​Start the Server

​Individual Demo Walkthrough

​Slack Demo

​5. Page Wrapper Reference

​6. State Dependencies

​7. Route Map Summary

Individual User Story

1. Onboarding Flow

1.1 Discovery

1.2 Sign-Up & First Login

1.3 Demo Onboarding (First-Time Wizard)

2. Sidebar Navigation

The Shrine Section

The Lounge Section

Ambient ShrineChat Widget

Additional Protected Pages (not in sidebar)

Backward Compatibility Redirects

3. Feature Walkthrough

3.1 HealthDM Dashboard (`/shrine/dashboard`)

3.2 Ambient ShrineChat Widget (All Pages)

3.3 Protocol Marketplace & Subscriptions

3.4 Protocol Adoption & Adherence

3.5 Health Profile (`/shrine/profile`)

3.6 Settings (`/shrine/settings`)

3.7 Notifications (`/shrine/notifications`)

3.8 Slack Integration (External)

3.9 Admin Token Management

3.10 MCP Integration (Developer)

4. Demo Run (Individual)

Prerequisites

Start the Server

Individual Demo Walkthrough

Slack Demo

5. Page Wrapper Reference

6. State Dependencies

7. Route Map Summary