CareDesk 247 — Product Documentation

1. Platform Overview

CareDesk 247 is an AI-powered practice management and scheduling platform designed for medical practices of all sizes. It provides end-to-end patient scheduling, automated notifications, digital intake forms, and an AI assistant — all accessible from a single dashboard.

Tech Stack

Architecture

• Multi-tenant SaaS — each practice is an isolated tenant with its own branding, settings, providers, and data
• Server-side rendering with React Server Components and client-side interactivity where needed
• API routes handle all data mutations; public endpoints use x-tenant-id header for tenant scoping
• Production deployment at www.caredesk247.com

2. Multi-Tenancy & Auth

Tenant Model

Each practice is a Tenant record with a unique slug, branding configuration (logo, name, primary color), timezone, and settings. All data — providers, patients, appointments, schedules — is scoped to a tenant via tenantId foreign keys.

Authentication

• Auth.js v5 with credentials provider (email + password)
• Passwords hashed with bcrypt
• Session-based authentication for staff dashboard access
• JWT tokens for API route protection

Roles

Public API Access

Public-facing API endpoints (booking, slot search, patient creation) use the x-tenant-id header to identify the tenant. No authentication is required for these endpoints, but rate limiting is applied.

Demo Tenant

The demo tenant sunrise-medical is pre-seeded with providers, schedules, and sample data. Real notifications (SMS/email) are blocked for this tenant to prevent accidental sends during testing.

3. Patient Booking Flow

Entry Points

• Embeddable widget — practices embed /embed/[tenantSlug] on their website via iframe
• Direct booking link — shared with patients via email, SMS, or social media
• Discover page — patients search for providers and book from search results

4-Step Booking Flow

Under the Hood

• Tenant branding fetched from /api/embed/[tenantSlug] endpoint
• Patient creation: auto-creates a User account with a temporary password and sends a set-password email
• Returning patients: if email matches an existing patient, consent preferences are updated and the existing record is reused
• Slot engine generates available time windows from provider schedules (see Section 6)
• Conflict checking prevents double-booking by verifying no overlapping appointments exist for the provider
• Rate limiting: 5 bookings per hour per IP address to prevent abuse
• Appointment created with status PENDING and bookingSource PATIENT_PORTAL (or AI_ASSISTANT if booked via chat)
• Confirmation token generated and included in email for one-click confirm/cancel links

4. Care AI Assistant

Care AI is a conversational scheduling assistant powered by Claude Sonnet via the Anthropic SDK. It uses a tool-use architecture where the AI model can call backend functions to look up data and perform actions.

Scheduling Tools

How It Works

• Patient sends a message via the chat widget on the booking or discover page
• Message and conversation history are sent to /api/ai/chat with the tenant ID
• The system loads tenant-specific context: agent name, knowledge base, practice name
• Claude processes the message with a custom system prompt and available tools
• If Claude needs data (e.g., available slots), it calls a tool; the result is fed back for another round
• Up to 5 tool-use iterations per message to handle complex multi-step requests
• Final text response is returned to the patient

Customization

• Agent name: each tenant can set a custom name (e.g., "Emma" instead of "Scheduling Assistant")
• Knowledge base: free-text field where practices can add FAQs, office hours, parking info, etc.
• The AI references the knowledge base naturally in conversation without quoting it verbatim

Voice Support

The chat widget includes voice input and output via the Web Speech API. Patients can speak their request (speech-to-text) and hear the AI response read aloud (text-to-speech). This works in modern browsers without any additional setup.

5. Notification System

Channels

• SMS — sent via Twilio. Phone numbers auto-normalized to E.164 format.
• Email — sent via Resend. Supports both plain text and HTML templates with inline CSS.

Consent Gating

Every notification checks the patient's consent before sending. SMS requires phoneConsent: true and email requires emailConsent: true. The booking flow sets both to true by default. Notifications for the demo tenant (sunrise-medical) are always blocked.

Template System

• Templates use {{variable}} interpolation (e.g., {{patientName}}, {{date}}, {{time}})
• Each tenant can customize templates via the staff dashboard
• If a tenant has no templates for a notification type, defaults are auto-created on first send

Notification Types

Practice Alerts

When a patient books online, an email alert is sent to the tenant's registered email address with full appointment details (patient name, contact info, provider, date/time, location). This ensures the front desk is immediately aware of new bookings.

Notification Tracking

Each send creates a Notification record in the database with status (pending/sent/failed), the external provider ID (Twilio SID or Resend ID), timestamp, and any error messages. This provides a full audit trail visible in the staff dashboard.

6. Appointment Reminders (Cron)

Automated reminders are sent via a daily cron job at /api/cron/send-reminders, triggered by Vercel Cron at 9 AM UTC.

Reminder Windows

• Cron requires CRON_SECRET header for authentication (auto-set by Vercel)
• Each reminder increments the remindersSent counter on the appointment to prevent duplicate sends
• Only CONFIRMED and PENDING appointments receive reminders
• Vercel Hobby plan limits cron to daily execution (schedule: 0 9 * * *)

7. Staff Dashboard

The staff dashboard at /staff/dashboard is the central management interface for practice staff. It requires authentication with ADMIN, STAFF, or PROVIDER role.

Dashboard Modules

8. Digital Intake Forms

Form Builder

Practices can build custom intake forms using a drag-and-drop form builder in the staff dashboard. Forms are composed of fields with configurable types.

Supported Field Types

AI-Powered PDF Conversion

Practices can upload existing PDF forms and have Claude Vision analyze them, extracting fields and converting them into digital form definitions automatically. This eliminates the need to manually recreate existing paper forms.

Auto-Send on Booking

• Forms flagged with autoSendOnBooking are automatically sent to new patients when they book
• A FormSubmission record is created with a unique access token
• Patient receives a FORM_REQUEST notification with a secure link
• Links expire after 7 days for security
• Duplicate submissions for the same form + appointment are prevented

9. Waitlist System

• Patients can join the waitlist when no suitable slots are available
• Waitlist entries capture preferences: preferred days of week, time range (earliest/latest), date range, and priority level
• When an appointment is cancelled, the system automatically finds the top 5 matching waitlist entries and sends WAITLIST_OFFER notifications
• Matching considers appointment type and optionally the specific provider
• Results are ordered by priority (descending) then creation date (ascending) — first-come, first-served within priority tiers
• Duplicate active entries for the same patient + appointment type are prevented

10. Password Reset

Forgot Password Flow

• Patient or staff member submits email to /api/auth/forgot-password
• A secure random token is generated and stored in the VerificationToken table
• An email is sent via Resend with a link to the reset password page
• Token expires after 1 hour
• Reset page at /reset-password?token=... validates the token and allows setting a new password

New Patient Account Setup

When a patient is auto-created during booking, a set-password email is sent with a 7-day token. This allows patients to claim their account and access the patient portal without the practice needing to manually create credentials.

11. Embeddable Widget

Practices can embed the CareDesk booking flow directly on their own website. This is the primary way practices deploy CareDesk to their patients.

How It Works

• Embed URL format: /embed/[tenantSlug]
• The embed page fetches tenant branding (logo, name, primary color) from the /api/embed/[tenantSlug] endpoint
• CORS headers are set to allow embedding from any origin
• The full booking flow runs within the embed, including visit type selection, provider choice, and appointment confirmation
• Practices add the embed via a simple iframe or link provided in the staff dashboard settings

Example Integration

<!-- Embed CareDesk booking on your website -->
<iframe
  src="https://www.caredesk247.com/embed/your-practice-slug"
  width="100%"
  height="700"
  frameborder="0"
  style="border: none; border-radius: 12px;"
></iframe>

12. API Reference

All API routes are under /api/. Public endpoints require the x-tenant-id header. Session endpoints require an authenticated session cookie.

13. Database Schema Overview

The database uses Prisma 7 with Neon PostgreSQL. All models are tenant-scoped (except global models like VerificationToken). Key models:

14. Environment Variables

15. Deployment

• Source code hosted on GitHub at veenomous/CareDesk
• Deployed via Vercel REST API (not auto-deploy from GitHub)
• Production URL: www.caredesk247.com
• Client practices embed the booking widget from the production URL on their own websites
• Example: allergy-family-care.vercel.app embeds booking from caredesk247.com/embed/allergy-family-care

Deployment Commands

# Push code to GitHub
git add -A && git commit -m "..." && git push

# Deploy to Vercel production
npx vercel --prod --yes

# Database schema updates
npx prisma db push

16. Marketing Pages

17. Roadmap