prd1.md

Product Requirements Document (PRD) v0.

Executive Summary

HolisticBook remains a lightweight, self-hosted booking platform tailored for holistic psychologists, prioritizing data ownership, privacy, and a serene user experience. This iteration refines the technical foundation to leverage Cloudflare D1 (edge SQL database) for all persistent data storage and Hono running on Cloudflare Workers for all API/database operations.

Key updates:

• Core database operations (availability, bookings, forms, client data) handled via D1 bindings in Hono routes.
• MVP focuses on simple, secure auth (e.g., magic links or basic JWT) to enable practitioner dashboard access.
• Post-MVP: Integrate Firebase Authentication for advanced features like social logins, email/password, and robust session management.
• Benefits: Global edge performance, low latency, scalable serverless architecture, and cost-effective (free tier sufficient for solo practices).

Target: MVP deployable rapidly using modern Cloudflare templates, with seamless local development via Wrangler and Vite.

User Stories

(No major changes; minor refinements for auth context)

As a Holistic Psychologist (Practitioner):

• I want to securely log in to my dashboard (initially via magic link; later Firebase) so only I can manage availability and view bookings.
• I want to set availability and session types persisted in D1 so they survive restarts and scale globally.
• I want all bookings and intake forms stored securely in D1 for easy querying and future analytics.

As a Client:

• (Unchanged) Public booking flow remains account-free for simplicity.

As a Developer/Practitioner (Post-MVP):

• I want to upgrade to Firebase Auth for better user management (e.g., password reset, Google login).

Concept Summary

• Architecture: Full-stack SPA with React frontend (Vite) served as static assets; dynamic routes and API handled by Hono on Cloudflare Workers/Pages.
• Data Flow: All CRUD operations route through Hono → D1 (edge-replicated SQLite). No external DB dependencies in MVP.
• Auth Evolution:
  • MVP: Simple email magic links or session cookies stored in D1/KV.
  • v1+: Replace with Firebase Auth (verified via middleware like @hono/firebase-auth or firebase-auth-cloudflare-workers).
• Design: Calm, minimalist UI unchanged.

Technical Summary

Base Template Recommendation (Updated for 2025):
Start with a modern Cloudflare full-stack template that natively supports Vite + React + Hono:

• Preferred: npm create cloudflare@latest -- --template=cloudflare/templates/react-router-hono-fullstack-template (includes React Router, shadcn/ui, Tailwind – excellent for dashboard).
• Alternative: Custom from create-hono (cloudflare-workers or cloudflare-pages template) + integrate Vite React SPA.
• Community options: jezweb/vite-flare-starter or similar for built-in D1 + Drizzle examples.

Core Tech Stack (Refined):

• Frontend: React 19 + TypeScript, Vite, Tailwind CSS, shadcn/ui (accessible components), TanStack Query/React Query for optimistic updates and caching.
• Backend/API: Hono (ultra-fast edge framework) – all routes under /api/*. Access D1 directly via c.env.DB (binding).
• Database: Cloudflare D1 (serverless edge SQL) – primary storage for:
  • Practitioners (profile, settings)
  • Availability rules (recurring slots, buffers)
  • Bookings (status, client info, intake responses)
  • Session types and custom forms
    Best practices:
  • Use Drizzle ORM for type-safe queries and migrations (highly recommended in 2025 templates).
  • Run migrations via wrangler d1 execute or Drizzle Kit.
  • Batch operations where possible for efficiency.
• Auth:
  • MVP: Basic magic-link auth (email via Resend) with sessions in D1 or KV.
  • Post-MVP: Integrate Firebase Auth using Hono middleware (e.g., @hono/firebase-auth or firebase-auth-cloudflare-workers). Verify ID tokens in protected routes; store minimal user data in D1.
• Payments: Stripe Checkout Sessions.
• Emails/Reminders: Resend (transactional) + Cloudflare Queue/Cron Triggers for scheduled reminders.
• Calendar: date-fns + custom recurring logic; UI with FullCalendar or Day.js picker.
• Deployment: Cloudflare Pages (for static + functions) or Workers – free tier, global edge, automatic previews via GitHub.
• Configuration (wrangler.toml example):

  [[d1_databases]]
  binding = "DB"                  # Available in Hono as c.env.DB
  database_name = "holisticbook"
  database_id = "<your-d1-id>"
  migrations_dir = "drizzle/migrations"

• Hono D1 Usage Example:

  app.get('/api/availability', async (c) => {
    const { results } = await c.env.DB.prepare('SELECT * FROM availability').all();
    return c.json(results);
  });

  With Drizzle: Type-safe, auto-migrated schemas.

MVP Scope (v0.1 Beta):

• D1 schema + migrations (availability, bookings, basic practitioner).
• Hono API routes for CRUD (protected minimally).
• Public booking flow + simple practitioner dashboard.
• Email confirmations (no reminders yet).

Future Iterations (to v1.0):

• Advanced reminders via Cron Triggers.
• Stripe payments.
• Custom intake form builder.
• Firebase Auth integration (social logins, better UX).
• Analytics dashboard.