PracticeNear Architecture Briefing

From: Jonathan Gudger, Systems Engineer To: Blake Toves, PM/GTM Date: 2026-03-26
Day 1 of 90 — Phase 1 Internal Prototype (target: Apr 24)
67K
Lines of Code
80+
Prisma Models
27
API Routes
20+
Integrations
63
Env Vars Needed
3
Env Vars Available

Decisions Required from Blake

Four items are blocked on your input. These must be resolved before development can begin.

CPI-3: Vercel Project Access
Recommended: Grant Jonathan project-level Member access on Vercel for holistic-health-marketplace. This allows env var pull without full team admin access.

Request sent 2026-03-26. Jonathan is linked to the project but cannot read environment variables. Without this, the full 63-variable configuration must be manually reconstructed.

Steps: Vercel Dashboard → holistic-health-marketplace → Settings → General → Project Members → Add Member (noboxcreatives email) → Role: Member

Also needed: confirm if any env vars are marked "Sensitive" (Owner-only access).

CPI-1: Database Strategy — Shared vs. Isolated
Recommended: Option B — Separate Neon project for Jonathan's development. Isolated, safe to experiment, seed data sufficient for Phase 1.

Option A: Shared Neon DB — risk of breaking Blake's data during development.

Option B: Separate Neon project — isolated, safe, uses seed data (6 practitioners, 5 clients, 8 bookings). Recommended

Option C: Both — read-only access to Blake's + own dev DB. Best for Phase 2.

Key question: Have the 60K+ imported listings been loaded into Blake's DB, or is that pending?

CPI-2: MVP Feature Scope Alignment
Recommended: Strip non-MVP features from Phase 1 UI. The codebase includes Enterprise B2B, GLP-1, LMS, Lab Orders, and Health Journaling — all marked deferred in the kickoff.

The schema has 80+ models. An estimated 30% serve core marketplace functions (search, booking, payments, claiming). The remaining 70% support features explicitly deferred in the CONTEXT.md kickoff notes.

Decision needed: Which domains must work in the Apr 24 prototype?

FeatureIn CodebaseMVP?Decision
Practitioner search + profilesFullYesProceed
Appointment booking (Cal.com)FullYesProceed
Payment processing (Whop)FullYesProceed
Profile claimingFullYesProceed
AI search agentPartialYesNeeds input
Enterprise B2BFullDeferredStrip?
GLP-1 programFullDeferredStrip?
LMS (courses)FullDeferredStrip?
Lab ordersFullDeferredStrip?
Health journalingFullDeferredStrip?
In-app messagingFullNot specifiedKeep?
CPI-4: Domain & Production Deployment
Recommended: First Production deployment after Phase 1 prototype approval (~Apr 24).

Currently all Vercel deployments are Preview — no Production deployment exists. Questions:

  • Is practicenear.com pointed at the Vercel project?
  • Is Preview-only intentional or a configuration gap?
  • When should the first Production deployment happen?

Current Priorities

Five work items that can proceed now or are blocked only on the decisions above.

CP-1: Bootstrap Local Dev

Create Neon DB, generate .env.local, install dependencies, push schema, seed data, verify app loads.

Blocked on: CPI-1 (DB strategy) + CPI-3 (Vercel access)

CP-2: Verify Build Parity

Run production build locally, compare against Blake's Vercel output, identify env-dependent failures.

Depends on: CP-1

CP-3: Fork Repository

Fork to jgatlit/holistic-health-marketplace with dual remotes (origin = fork, upstream = Blake's).

Ready — no blockers

CP-4: Independent Vercel Project

Create new project under ai-chemist scope linked to fork. Push env vars, deploy independently.

Depends on: CP-1, CP-3

CP-5: Scope Assessment

Map which schema domains are active in UI vs. scaffolded vs. dormant. Recommend minimum viable schema.

Depends on: CP-1
CPI-1 + CPI-3 CP-1: Bootstrap CP-2: Build Parity CP-5: Scope
CP-3: Fork CP-4: Vercel Project DP-1: Typesense DP-2: Knowledge Graph

Technology Stack

20+ integrated services across 6 infrastructure layers.

LayerTechnologyRoleDomain
FrontendNext.js 14.2 (App Router)TypeScript, Tailwind CSS, src/ directoryCore
ORMPrisma 6.x84KB schema, 80+ models, db push strategyCore
DatabaseNeon PostgreSQLServerless, auto-scalingCore
AuthAuth.js v5Email/password + Google OAuth, JWT, MFACore
PaymentsWhopDirect charges, checkout sessions, refundsFinancial
Business CreditCapital OSWallets, auto-sweep, card managementFinancial
SchedulingCal.com v2Managed users, event types, slot availabilityCore
EmailResendTransactional (verification, bookings, reviews)Core
SMSTwilioBooking reminders with credit systemClinical
AIClaude HaikuSession notes (SOAP), rate-limited 20/dayClinical
VideoDaily.coHIPAA-compliant telehealth roomsClinical
Health DataTerra API200+ wearable providersClinical
InsuranceThimbleEmbedded GL + professional liabilityEnterprise
ErrorsSentryServer, client, edge (10% sample rate)Infra
Rate LimitingUpstash RedisFalls back to in-memoryInfra
StorageVercel BlobFile uploads and attachmentsInfra
AnalyticsGTM + GA4 + Meta + TikTok + LinkedIn5-platform conversion trackingInfra
Enrichmentpracticenear-engine (Python)Google Maps, static pages, llms.txtCore

Integration Architecture

Core Data Flows

The three critical pipelines that define the marketplace: booking lifecycle, payment/earnings, and listing-to-profile claiming.

Booking Lifecycle

Payment & Earnings Flow

Practitioner Claiming & Onboarding

Schema Scope Assessment

80+ models across 15 domains. Estimated ~30% serve the MVP. The remaining 70% support deferred features that are already scaffolded in the codebase.

Model Distribution by Domain

DomainModelsMVP StatusNotes
Auth & Users5ActiveUser, Account, Session, tokens
Practitioner & Services5ActivePractitioner (60+ fields!), Service, Credential, Availability
Bookings1ActiveFull lifecycle: PENDING → COMPLETED/NO_SHOW
Payments5ActivePayment, Refund, PackageCredit, Wallet, WalletTransaction
Listings & Search2ActiveImportedListing, ListingSearchDocument — Typesense target
Communication8PartialNotifications MVP; messaging, email campaigns may defer
Clinical5PartialSessionNote (AI) likely MVP; IntakeForm, TreatmentProtocol may defer
Health Tools6DeferredJournal, symptoms, supplements, food diary, photos
Health Data (Terra)3DeferredWearable connections, snapshots, sharing
Lab Integration2Deferred3 providers: Microbiome Labs, Rupa, Everlywell
Enterprise B2B5DeferredOrganization, WellnessProgram, BulkBooking, ApiKey
GLP-1 Program5DeferredAffiliate, referral, payout (80/20 split)
LMS4DeferredCourse, Lesson, Enrollment, Completion
HIPAA Compliance3PartialSchema ready; enforcement for Phase 2
Platform & Audit6+ActivePlatformConfig, AuditLog, ProcessedWebhook, etc.

API Surface

27 API routes, 20+ server action files, 8 cron jobs, 6 webhook handlers — all following consistent patterns.

Route Distribution

7 Public Routes

Practitioner search, list, services, slot availability, tracking, health check, auth register/verify

8 Cron Jobs

Auto-complete, auto-sweep, reminders, SMS reminders, no-shows, payouts, reindex, review follow-ups

6 Webhooks

Cal.com, Whop, Capital OS, GLP-1, Lab Results, Terra — all HMAC-SHA256 verified with idempotency

1 Admin + 2 Org API

Bulk listing import (max 1000/batch), v1 API for organizations with scoped API keys

Middleware Pipeline

User Flows

Three primary user journeys through the marketplace.

Consumer

  1. Search practitioners
  2. View profile
  3. Select service + time slot
  4. Register/login
  5. Pay via Whop
  6. Attend session (video/in-person)
  7. Leave review
  8. Track health data

Practitioner

  1. Claim pre-generated profile
  2. Complete onboarding (KYC)
  3. Set up services + availability
  4. Receive bookings
  5. Conduct sessions
  6. Write session notes (AI)
  7. Manage earnings (wallet)
  8. Optional: credit, insurance, LMS

Admin

  1. Bulk import listings (60K+)
  2. Review claim requests
  3. Platform configuration
  4. Monitor audit logs
  5. Analytics snapshots

Practitioner Claiming & Activation Pipeline

Deferred Priorities

Five enhancement tracks that activate after Phase 1 gates clear.

DP-1: Typesense Search

Replace Prisma-based ListingSearchDocument with Typesense parametric filtering. Amazon-style intelligent search at 60K+ scale.

Gate: CP-1 + CP-5 complete

DP-2: Knowledge Graph

Semantic search layer for AI agent-guided discovery. "Find someone near me for lower back pain."

Gate: DP-1 complete (layers on top)

DP-3: HIPAA Hardening

Infrastructure migration eval (Railway), compliant LLM selection, encryption enforcement. Schema already prepared.

Gate: Phase 2 (real health data enters)

DP-4: Load Testing

Agentic browsers simulating 1,000+ concurrent users. No test infra beyond Playwright smoke tests currently.

Gate: Phase 2 (core flows stable)

DP-5: Dashboard Simplification

Strip PMS-level complexity from practitioner dashboard. Assess first, then simplify with Blake's agreement.

Gate: CP-5 complete (scope assessed)

90-Day MVP Timeline

Risk Register

RiskLikelihoodImpactMitigation
Schema too large for MVP — 80+ models create cognitive overhead and slow iteration High Medium CP-5: Assess and identify minimum viable schema. Hide non-MVP routes.
Vercel-provisioned integrations (Neon, KV, Blob) may not be duplicable to Jonathan's scope Medium High CPI-3: Get Member access. Fallback: provision own integrations independently.
95 stale branches in Blake's repo create merge conflict risk Medium Low Work from main only. Clean up branches after alignment with Blake.
No Production deployment — go-live process undefined Medium High CPI-4: Define production deployment workflow before Phase 2.
Prisma db push without migrations — schema changes can cause data loss with real data High High Implement migration strategy before real practitioner data enters the system.
6% platform fee hardcoded in PlatformConfig seed — no admin UI to adjust Low Medium Verify admin dashboard can modify or plan direct DB update path.