HHE Practitioner Directory — Architecture Decisions

1

Search Architecture Priority

Current search is SQL-based (Prisma queries). Typesense client is initialized but not integrated. SQL search lacks ranking, fuzzy matching, and performs O(n) in-memory distance filtering.

A) Keep SQL-only

No new complexity. Works for current scale. No fuzzy matching or ranking.

B) Integrate Typesense now

Fuzzy search, typo tolerance, geo-native filtering, sub-ms responses. Client already initialized.

C) Typesense after MVP launch

Defer complexity. SQL limitations persist through MVP.

2

Payment Flow Model

Stripe client initialized (API v2025-10-29.clover). stripe_account_id field exists on practitioners. No payment endpoints built yet.

A) Direct charge

Platform charges client, pays practitioner manually. Simple but high manual effort.

B) Stripe Connect marketplace

Split payments, automated payouts, 1099 reporting. Standard marketplace model.

C) Escrow model

Hold payment until appointment completes. Highest trust, most complex.

3

Phone Number Source

Users table has no phone field. SMS reminder pipeline executes but produces zero deliveries — all reminders bounce with NO_PHONE_NUMBER error. This is the #1 blocking issue.

A) Add phone to users table

New migration. Collect during signup. Full control, requires UI.

B) Source from Clerk profile

Pull from Clerk user profile via API. No migration needed. Depends on Clerk data availability.

C) Both: users table + Clerk sync

Store in users table, sync from Clerk as default, allow manual override in dashboard.

4

Redis Caching Strategy

Redis client initialized with singleton pattern and retry strategy. Currently only used for health check PING. No data caching implemented.

A) Practitioner listings

Cache full practitioner objects. 5-10 min TTL. Reduces DB load for browsing.

B) Search results

Cache by query parameter hash. 5 min TTL. Eliminates repeat query computation including distance filtering.

C) Session data

24h TTL. Reduces Clerk API calls. Least performance impact.

5

Dashboard Priority Features

Dashboard layout and routes exist. All pages are placeholder server components. Directory is usable by clients without a dashboard (search, view, browse). Practitioners need management tools.

A) Practitioner dashboard first

Profile editing, service management, booking calendar, earnings, reviews. Drives practitioner activation.

B) Client dashboard first

Booking history, favorites, review management, payment history. Drives client engagement.

C) Both minimal

Basic profile + booking list for both roles. Broad but shallow.

6

Review Moderation Model

is_published and moderated_at fields already exist in reviews table. No moderation logic implemented yet.

A) Admin approval required

Review submitted to admin queue. Approve/reject before publishing. Higher quality, slower velocity.

B) Auto-publish with flagging

Published immediately. AI/rule-based flagging queues suspicious reviews for admin. Higher velocity.

7

Availability & Time Slot Granularity

Current availability stores day_of_week + start_time/end_time strings. Booking flow has no slot validation or double-booking prevention.

A) Keep day-level availability

Simple. "Available on Monday." No time precision. Current state.

B) Add time slot booking

Precise scheduling, conflict detection, buffer time between appointments, timezone-aware display.

Architecture Decision Capture