System Requirements Document for dental-clinic-hariyom

1. Introduction

This document specifies the production-ready, full-stack website for HARIYOM DENTAL CLINIC, a single-doctor, family-run dental practice led by Dr. Priya Patel, operating 10 AM–8 PM and serving patients in English, Hindi and Gujarati.

The product intent is to deliver an original premium dental-tech experience that carries a visitor through the patient journey WOW → CURIOUS → TRUST → UNDERSTAND → COMFORTABLE → CHAT WITH AI → BOOK. It combines a cinematic, scroll-driven 3D tooth experience, an interactive educational tooth explorer, a database-driven service catalog, a multilingual AI dental receptionist named Yogesh, an AI-assisted appointment engine, a staff admin dashboard and CMS, consent-based WhatsApp confirmation, and rigorous security, privacy, SEO, performance and accessibility practice.

The audience is threefold: patients (prospective and existing) who need to understand treatments, feel reassured, and book or manage an appointment without calling; clinic admin/staff who operate the schedule, leads, chats and published clinic knowledge without developer help; and the engineering/integration team who build, test, deploy and maintain the system.

The core feeling the product must produce is: "Technology is advanced here, but the care still feels human."

2. System Overview

Hariyom Dental Clinic's website is a Next.js + React + TypeScript + Tailwind application with a server-side backend (Next.js API routes or Python FastAPI), PostgreSQL with Prisma, a vector store (pgvector or Qdrant) for retrieval-augmented generation, Redis caching, S3-compatible asset storage, and OpenAI as the LLM and embedding provider. It integrates the Meta WhatsApp Business API (or an approved provider) for consent-based appointment confirmation and optional reminders.

Actors. The accepted active human personas are the Prospective Patient, the Existing Patient, and the Clinic Admin / Staff. Non-human actors include the AI Dental Receptionist (Yogesh) as a system-operated assistant, the LLM/RAG service, the WhatsApp Business provider, and the backend/database which owns all business logic and durable state.

Accepted behavior. The system presents a cinematic homepage with a scroll-scrubbed 3D tooth; an interactive tooth explorer with rotate, zoom and five clickable anatomical hotspots; a procedure visualizer with an educational root-canal sequence; a twelve-service catalog with 3D icons; doctor and trust content; a clinic-owned gallery with lightbox; a multilingual AI receptionist with eight quick actions and strict non-diagnostic limits; an appointment engine with a defined state machine and statuses; a staff admin dashboard with calendar and record actions; a CMS that publishes without a code deploy; consent-based WhatsApp messaging; and legal pages (Privacy Policy, Terms, Medical Disclaimer).

Ownership. All patient-facing and staff-facing interaction surfaces are first-party application pages. WhatsApp message delivery is owned by the external provider. LLM inference, embeddings and vector retrieval are owned by the AI/RAG service. All appointment state transitions, validation, authorization and durable writes are owned by the backend and database — never by the LLM.

Narrow exclusions. The AI receptionist is a receptionist and educational assistant, not a doctor: it never diagnoses, prescribes medicine or dosage, guarantees outcomes, replaces dental consultation, invents facts, or claims certainty. The interactive tooth and procedure visualizer are educational only and never diagnose or imply AI diagnosis. No credentials, testimonials, prices or claims may be invented. The supplied Hariyom logo/mascot image and the user-provided Instagram Reel are used only as inspiration; the Reel, other clinics and copyrighted assets must not be copied. The generic indigo/blue-on-white SaaS template is forbidden.

2a. Product Interpretation and Delivery Boundary

The public site is anonymously reachable: a visitor can read the homepage, services, trust content, gallery, educational tooth and procedure content, legal pages, and can open Yogesh and ask questions without any account. Booking an appointment is also reachable from the public entry points, and the appointment flow collects the patient's details directly.

Durable, revisitable patient state — the ability to return later and reschedule or cancel an existing appointment — requires the patient to be identifiable to the clinic. This is established through a first-use enrollment interaction and a returning verification interaction, both anonymously reachable, with the protected appointment record remaining unavailable until identity is established. Staff access to the admin dashboard and CMS is provisioned by clinic administration and verified at a role-appropriate staff login; protected operational state is unavailable until that verification succeeds.

WhatsApp confirmation and reminders are delivered by the external WhatsApp Business provider under consent and approved templates. Voice interaction (ElevenLabs + Whisper/STT + OpenAI) is a future capability on the same backend and is not part of current acceptance.

2b. Source Content Inventory

No reference directive in this project declares content_source authority. The supplied Hariyom logo/mascot image and the user-provided Instagram Reel are declared inspiration_only (visual inspiration / brand inspiration) and therefore contribute no product names, copy, facts or capabilities. No source content inventory is included.

2c. Page Content and Component Coverage

Home

• Information/state: Cinematic hero with headline "Your Smile Deserves Exceptional Care.", supporting line "Modern dentistry, advanced technology, and compassionate care — designed around you.", primary CTA "Book an Appointment", secondary CTA "Chat with AI Dental Assistant"; trust strip; interactive tooth teaser; services preview; treatment journey; Why Hariyom; doctor; AI assistant introduction; education; genuine testimonials; gallery preview; appointment prompt; contact; footer.
• Primary actions: Book an Appointment; Chat with AI Dental Assistant; navigate to Services, Teeth Explorer, Procedure Visualizer, Trust, Gallery, Appointment, Contact.
• Supporting actions: Scroll-driven 3D story; open Yogesh; open gallery lightbox; click phone/directions.
• Domain entities: clinic_settings, services, doctors, testimonials, gallery assets, knowledge documents.
• Component responsibilities: components/3d (hero tooth, scroll-scrubbed camera arc, low-GPU/mobile fallback, reduced-motion still frame), components/animations (section reveals, scroll cue), components/services (service cards with 3D icons), components/chatbot (floating Yogesh avatar with breathing pulse), components/ui (nav, footer, buttons, hairline panels).
• States: loading (glowing tooth outline + "Preparing your smile experience…"); empty (testimonials/gallery show admin-approved placeholders only); success (hero renders, 3D loads after critical content); error (3D failure falls back to static/SVG asset without blocking scroll); recovery (retry or continue with fallback).

Services

• Information/state: The twelve approved services — check-up, cleaning, root canal, implants, crowns/bridges, whitening, cosmetic, orthodontic, pediatric, wisdom tooth, gum care, smile makeover — each with a 3D icon, approved short description, "Learn More" and "Book Appointment".
• Primary actions: Learn More; Book Appointment.
• Supporting actions: Hover subtle 3D tilt/depth/glow on the icon; navigate to Appointment with the service preselected.
• Domain entities: services, clinic_settings.
• Component responsibilities: components/services (card grid 3-up/2-up/1-up, flat hairline surface, depth inside the 3D icon), components/3d (per-service instrument render).
• States: loading (skeleton cards); empty (no unapproved service is ever shown); success (approved catalog rendered); error (safe message, no stack trace); recovery (retry fetch).

AI Assistant

• Information/state: Yogesh — AI Dental Receptionist; greeting "Hi! I'm Yogesh, Hariyom Dental Clinic's AI Dental Receptionist. How can I help you today?"; quick actions Book Appointment, Reschedule, Cancel, Ask About Treatments, Clinic Timings, Location, Emergency Help, Talk to Clinic Staff; language auto-detection for English/Hindi/Gujarati; pinned clinic hours and language switcher.
• Primary actions: Send a message; choose a quick action; complete the appointment state machine; request staff escalation.
• Supporting actions: Switch language; view clinic timings; view location; trigger emergency guidance.
• Domain entities: chat sessions/messages, knowledge documents, appointments, leads, notifications.
• Component responsibilities: components/chatbot (full-height panel, listening ring, message list, quick actions, language switcher), lib/ai (LLM orchestration), lib/rag (approved-source retrieval and filtering).
• States: loading (assistant pulse, typing indicator); empty (greeting only); success (grounded answer or completed appointment step); error (unknown-information response "I don't have that information right now. I can connect you with the clinic team."); recovery (staff escalation, emergency guidance, retry).

Teeth Explorer

• Information/state: Interactive tooth with rotate, zoom and hotspots; clickable regions Gum, Enamel, Dentin, Root, Nerve; short approved educational panel per region.
• Primary actions: Rotate; zoom; select a hotspot; read the educational panel.
• Supporting actions: Close panel; reset view.
• Domain entities: knowledge documents (approved education).
• Component responsibilities: components/3d (model, hotspots, camera controls, fallback), components/ui (floating hairline-bordered panel anchored to the hotspot).
• States: loading (tooth loader); empty (no unapproved explanation is shown); success (panel opens with approved text); error (fallback static asset); recovery (reset and retry). Every panel closes with the fixed line "Educational illustration only — your dentist must examine you in person."

Procedure Visualizer

• Information/state: Educational procedure sequences, including the root canal example: problem → cross-section → infection → cleaning → filling → restoration → healthy result; plus tooth→smile, inside-tooth enamel→dentin→pulp, cleaning particles, dental scan/AI interface, implant, braces, smile transformation, and clinic transition.
• Primary actions: Play/step through a sequence; select a procedure.
• Supporting actions: Pause; restart; read the disclaimer.
• Domain entities: knowledge documents (approved education).
• Component responsibilities: components/3d (sequence animation, particles, scan interface), components/animations (step transitions).
• States: loading (tooth loader); empty (no unapproved sequence); success (sequence plays with the educational disclaimer visible); error (fallback still frames); recovery (restart). The disclaimer states illustrations are educational and vary by patient, and never implies AI diagnosis.

Trust

• Information/state: Dr. Priya Patel profile with photo placeholder, verified qualifications, experience, practice areas and patient-first philosophy; Why Hariyom (patient-first care, modern technology, comfortable environment, personalized treatment, transparent communication, family-friendly care); genuine clinic-provided testimonials, otherwise admin placeholders.
• Primary actions: Read the doctor profile; read Why Hariyom; read testimonials; Book an Appointment.
• Supporting actions: Navigate to Gallery; navigate to Services.
• Domain entities: doctors, clinic_settings, testimonials.
• Component responsibilities: components/ui (profile, philosophy, testimonial list), CMS-driven content binding.
• States: loading (skeleton); empty (admin placeholder testimonial only, clearly marked); success (verified content rendered); error (safe message); recovery (retry).

Gallery

• Information/state: Clinic-owned media only, with lightbox and lazy loading.
• Primary actions: Open an image in the lightbox; move between images; close.
• Supporting actions: Lazy-load on scroll; keyboard navigation within the lightbox.
• Domain entities: gallery assets (S3-compatible storage), clinic_settings.
• Component responsibilities: components/ui (responsive grid, lightbox, lazy loading).
• States: loading (progressive placeholders); empty (no non-clinic-owned asset is ever shown); success (lightbox opens); error (broken-asset fallback); recovery (retry).

Appointment

• Information/state: Collection of name, phone, email, preferred date/time, new/existing patient, reason and language; availability lookup; summary; explicit confirmation; consent statement "By continuing, you agree that your information may be used to respond to your request and manage your appointment."
• Primary actions: Enter details; view availability; review summary; explicitly confirm; submit booking.
• Supporting actions: Change language; edit a step; cancel the flow.
• Domain entities: patients, appointments, doctors, services, clinic_settings, notifications.
• Component responsibilities: components/booking (step form, summary, confirmation), lib/db (backend-owned writes), lib/whatsapp (confirmation dispatch).
• States: loading (availability fetch); empty (no slots for the chosen date, offer alternatives); success (booking created, confirmation shown, WhatsApp dispatched under consent); error (validation error via Zod/equivalent, safe message, no stack trace); recovery (retry, choose another slot, or escalate to staff).

Contact

• Information/state: Clinic contact details, hours 10 AM–8 PM, location, directions, phone, and an inquiry/lead form with the consent statement.
• Primary actions: Submit an inquiry; call; get directions; request staff contact.
• Supporting actions: Navigate to Appointment; open Yogesh.
• Domain entities: leads, clinic_settings, notifications.
• Component responsibilities: components/ui (contact form, map/directions link), lib/db (lead persistence).
• States: loading (submitting); empty (no prior inquiry); success (inquiry recorded, acknowledgement shown); error (validation or delivery failure, safe message); recovery (retry).

Privacy Policy

• Information/state: How sensitive health information is handled, consent context, retention, and patient rights.
• Primary actions: Read the policy.
• Supporting actions: Navigate to Terms and Medical Disclaimer.
• Domain entities: clinic_settings (policy content).
• Component responsibilities: components/ui (long-form reading layout).
• States: static content; loading (skeleton); error (safe message); recovery (retry).

Terms

• Information/state: Terms governing product and appointment usage.
• Primary actions: Read the terms.
• Supporting actions: Navigate to Privacy Policy and Medical Disclaimer.
• Domain entities: clinic_settings.
• Component responsibilities: components/ui (long-form reading layout).
• States: static content; loading (skeleton); error (safe message); recovery (retry).

Medical Disclaimer

• Information/state: The non-diagnostic nature of the AI receptionist and all educational illustrations; the requirement that a dentist must examine the patient in person.
• Primary actions: Read the disclaimer.
• Supporting actions: Navigate to Privacy Policy and Terms.
• Domain entities: clinic_settings.
• Component responsibilities: components/ui (long-form reading layout).
• States: static content; loading (skeleton); error (safe message); recovery (retry).

Patient Appointments

• Information/state: The signed-in patient's appointment records with current status (PENDING, CONFIRMED, RESCHEDULED, CANCELLED, COMPLETED, NO_SHOW), date/time, doctor and reason.
• Primary actions: View an appointment; reschedule; cancel.
• Supporting actions: Request staff contact; view WhatsApp confirmation status.
• Domain entities: patients, appointments, doctors, notifications.
• Component responsibilities: components/booking (record list, reschedule and cancel controls), lib/db (backend-owned state transitions), lib/whatsapp (updated confirmation dispatch).
• States: loading (skeleton); empty (no appointments yet, offer to book); success (status updated to RESCHEDULED or CANCELLED and confirmation dispatched); error (authorization or validation failure, safe message); recovery (retry or escalate to staff).

Admin Dashboard

• Information/state: Appointments, leads, chats, requests, inquiries, service interest and analytics; day/week/month calendar views.
• Primary actions: Confirm; reschedule; cancel; complete; contact; add note.
• Supporting actions: Filter by day/week/month; open a chat transcript; open a lead.
• Domain entities: appointments, patients, leads, chat sessions/messages, notifications, admins, audit_logs.
• Component responsibilities: components/ui (calendar, tables, action controls), lib/db (authorized writes), lib/security (RBAC, audit logging).
• States: loading (skeleton); empty (no records in range); success (action applied and audit-logged); error (authorization or validation failure, safe message); recovery (retry).

CMS

• Information/state: Editable clinic info, doctor profile, services, FAQs, testimonials, gallery, hours, appointment settings, AI knowledge base and WhatsApp templates.
• Primary actions: Edit and publish content; upload clinic-owned gallery assets; manage approved knowledge documents.
• Supporting actions: Preview; revert; manage WhatsApp templates.
• Domain entities: clinic_settings, doctors, services, testimonials, gallery assets, knowledge documents, admins, audit_logs.
• Component responsibilities: components/ui (editors, uploaders, publish controls), lib/db (authorized writes), lib/rag (knowledge re-indexing), lib/security (RBAC, audit logging).
• States: loading (skeleton); empty (no content of a type yet); success (published live with no developer deploy); error (validation or authorization failure, safe message); recovery (retry, revert to previous version).

Login

• Information/state: Returning verification for patients and staff accessing durable appointment or operational records.
• Primary actions: Enter credentials; verify; continue to the intended protected destination.
• Supporting actions: Navigate to Sign Up (patients) or Admin Login (staff); recover access.
• Domain entities: patients, admins, audit_logs.
• Component responsibilities: lib/security (secure session, secure cookies, session expiry, rate limiting, CSRF protection).
• States: loading (verifying); empty (initial form); success (redirect to the intended protected destination); error (generic safe failure, no account enumeration); recovery (retry, rate-limit messaging).

Sign Up

• Information/state: First-use enrollment for a self-starting patient who needs durable appointment continuity.
• Primary actions: Provide details; accept the consent statement; create the account.
• Supporting actions: Navigate to Login; read Privacy Policy.
• Domain entities: patients, audit_logs.
• Component responsibilities: lib/security (input validation, secure session, secure cookies).
• States: loading (submitting); empty (initial form); success (account created, redirected to the intended protected destination); error (validation failure, safe message); recovery (retry).

Admin Login

• Information/state: Role-appropriate staff verification for the protected admin and CMS lifecycle; staff provisioning remains controlled by administration.
• Primary actions: Enter staff credentials; verify; continue to Admin Dashboard or CMS.
• Supporting actions: Navigate to Login; recover access.
• Domain entities: admins, audit_logs.
• Component responsibilities: lib/security (RBAC, secure session, session expiry, rate limiting, audit logging).
• States: loading (verifying); empty (initial form); success (redirect to Admin Dashboard or CMS); error (generic safe failure); recovery (retry, rate-limit messaging).

3. Functional Requirements

FR-1 — Clinic identity and hours. As a Prospective Patient, I should see the clinic name HARIYOM DENTAL CLINIC, the doctor Dr. Priya Patel, and the hours 10 AM–8 PM, so that I know who I am dealing with and when they are open. Provenance: explicit. Lifecycle: initiator — visitor; trigger — page load; observable result — clinic identity and hours rendered; access — anonymous; failure/recovery — CMS-sourced content fallback; continuation — navigate to Services or Appointment.

FR-2 — Multilingual experience. As a Prospective Patient, I should experience the site in English, Hindi or Gujarati, so that I can understand the clinic in my own language. Provenance: explicit. Lifecycle: initiator — visitor; trigger — language selection or auto-detection; observable result — content and assistant responses in the selected language; access — anonymous; failure/recovery — fall back to English; continuation — continue browsing or chatting.

FR-3 — Cinematic hero. As a Prospective Patient, I should see the headline "Your Smile Deserves Exceptional Care." with the supporting line "Modern dentistry, advanced technology, and compassionate care — designed around you.", a primary CTA "Book an Appointment" and a secondary CTA "Chat with AI Dental Assistant", so that I immediately understand the offer and my next step. Provenance: explicit. Lifecycle: initiator — visitor; trigger — homepage load; observable result — hero rendered with both CTAs; access — anonymous; failure/recovery — static fallback frame; continuation — click a CTA.

FR-4 — 3D hero scroll story. As a Prospective Patient, I should see a realistic 3D tooth in a clean medical environment starting with a macro enamel view, where on scroll the camera moves around and inside the tooth, gums/particles/light subtly animate, the tooth becomes healthier, and HARIYOM DENTAL CLINIC is revealed, following the sequence tooth→rotate→enter→structure→treatment→healthy→booking. Provenance: explicit. Lifecycle: initiator — visitor; trigger — scroll; observable result — scrubbed camera arc and final clinic reveal; access — anonymous; failure/recovery — low-GPU/mobile fallback and reduced-motion still frame; continuation — reach the booking CTA. Animation must never block scrolling or hurt performance.

FR-5 — 3D technology and asset discipline. As the engineering team, I should implement the 3D experience with Three.js, React Three Fiber, Drei, GSAP and/or Framer Motion using optimized GLB/GLTF, Draco/Meshopt compression, realistic materials and studio/rim lighting, so that the hero is premium and performant. Provenance: explicit. Lifecycle: initiator — system; trigger — 3D scene initialization; observable result — optimized model rendered; access — anonymous; failure/recovery — fallback asset; continuation — user continues scrolling.

FR-6 — Interactive tooth controls. As a Prospective Patient, I should rotate and zoom the interactive tooth and click hotspots for Gum, Enamel, Dentin, Root and Nerve, so that I can explore tooth anatomy at my own pace. Provenance: explicit. Lifecycle: initiator — visitor; trigger — drag, pinch/scroll, hotspot click; observable result — model rotates/zooms and a hotspot panel opens; access — anonymous; failure/recovery — fallback static asset; continuation — close panel and continue.

FR-7 — Educational panels, never diagnosis. As a Prospective Patient, I should see short approved educational panels per region that never diagnose, so that I learn without receiving medical advice. Provenance: explicit. Lifecycle: initiator — visitor; trigger — hotspot selection; observable result — approved educational text with the fixed line "Educational illustration only — your dentist must examine you in person."; access — anonymous; failure/recovery — no unapproved text is ever shown; continuation — explore another region or book.

FR-8 — Original 3D animations. As a Prospective Patient, I should see the original animations tooth→smile, inside-tooth enamel→dentin→pulp, cleaning particles, dental scan/AI interface, implant, braces, smile transformation and clinic transition, so that treatments feel understandable and human. Provenance: explicit. Lifecycle: initiator — visitor; trigger — sequence selection or scroll; observable result — animation plays; access — anonymous; failure/recovery — fallback still frames; continuation — continue to the next sequence or book.

FR-9 — Procedure visualizer. As a Prospective Patient, I should step through the root canal sequence problem→cross-section→infection→cleaning→filling→restoration→healthy result, with a clear statement that illustrations are educational and vary by patient and no implication of AI diagnosis. Provenance: explicit. Lifecycle: initiator — visitor; trigger — procedure selection; observable result — sequence steps with the disclaimer visible; access — anonymous; failure/recovery — fallback still frames; continuation — book an appointment.

FR-10 — Service catalog. As a Prospective Patient, I should see the twelve services — check-up, cleaning, root canal, implants, crowns/bridges, whitening, cosmetic, orthodontic, pediatric, wisdom tooth, gum care, smile makeover — each with a 3D icon, an approved description, "Learn More" and "Book Appointment". Provenance: explicit. Lifecycle: initiator — visitor; trigger — Services page load; observable result — approved catalog rendered; access — anonymous; failure/recovery — safe message; continuation — Learn More or Book Appointment.

FR-11 — Service card interaction. As a Prospective Patient, I should see a subtle 3D tilt/depth/glow on hover over a service card, so that the catalog feels premium without clutter. Provenance: explicit. Lifecycle: initiator — visitor; trigger — hover; observable result — icon tilts with depth; access — anonymous; failure/recovery — reduced-motion disables the tilt; continuation — click a CTA.

FR-12 — Approved clinic data only. As the clinic, I should have services and all published facts sourced only from approved clinic data, so that no credential, testimonial, price or claim is invented. Provenance: explicit. Lifecycle: initiator — Clinic Admin / Staff; trigger — CMS publish; observable result — only approved content is live; access — protected CMS; failure/recovery — reject unapproved content; continuation — publish approved content.

FR-13 — Doctor profile. As a Prospective Patient, I should see Dr. Priya Patel's profile with a photo placeholder, verified qualifications, experience, practice areas and patient-first philosophy, so that I can trust the clinician. Provenance: explicit. Lifecycle: initiator — visitor; trigger — Trust page load; observable result — verified profile rendered; access — anonymous; failure/recovery — placeholder shown until verified content is supplied; continuation — book an appointment.

FR-14 — Why Hariyom. As a Prospective Patient, I should see patient-first care, modern technology, comfortable environment, personalized treatment, transparent communication and family-friendly care, so that I understand the clinic's values. Provenance: explicit. Lifecycle: initiator — visitor; trigger — Trust page load; observable result — six value statements rendered; access — anonymous; failure/recovery — CMS fallback; continuation — continue to testimonials or booking.

FR-15 — Genuine testimonials. As a Prospective Patient, I should see only genuine clinic-provided testimonials, or clearly marked admin placeholders, so that I am never misled. Provenance: explicit. Lifecycle: initiator — Clinic Admin / Staff; trigger — CMS testimonial entry; observable result — verified testimonial published; access — protected CMS; failure/recovery — placeholder used only with admin approval; continuation — read more or book.

FR-16 — Clinic-owned gallery. As a Prospective Patient, I should browse a gallery of clinic-owned assets with lightbox and lazy loading, so that I see the real clinic. Provenance: explicit. Lifecycle: initiator — visitor; trigger — Gallery page load; observable result — images lazy-load and open in a lightbox; access — anonymous; failure/recovery — broken-asset fallback; continuation — close lightbox and continue.

FR-17 — Yogesh identity and greeting. As a Prospective Patient, I should meet a floating 3D tooth/assistant chatbot named "Yogesh – AI Dental Receptionist" with the greeting "Hi! I'm Yogesh, Hariyom Dental Clinic's AI Dental Receptionist. How can I help you today?", warm, professional, calm, caring and human-like. Provenance: explicit. Lifecycle: initiator — visitor; trigger — chatbot open; observable result — greeting rendered; access — anonymous; failure/recovery — static avatar fallback; continuation — choose a quick action or type.

FR-18 — Yogesh quick actions. As a Prospective Patient, I should use the quick actions Book Appointment, Reschedule, Cancel, Ask About Treatments, Clinic Timings, Location, Emergency Help and Talk to Clinic Staff, so that I can reach my goal in one tap. Provenance: explicit. Lifecycle: initiator — visitor; trigger — quick action selection; observable result — the corresponding flow starts; access — anonymous; failure/recovery — fall back to free-text chat; continuation — complete the flow.

FR-19 — Yogesh language auto-detection. As a Prospective Patient, I should have Yogesh auto-detect English, Hindi or Gujarati, so that I can converse naturally. Provenance: explicit. Lifecycle: initiator — visitor; trigger — message sent; observable result — reply in the detected language; access — anonymous; failure/recovery — default to English; continuation — continue the conversation.

FR-20 — Yogesh role limits. As the clinic, I should ensure Yogesh never diagnoses, prescribes medicine or dosage, guarantees outcomes, replaces dental consultation, invents facts or claims certainty, so that patients are protected. Provenance: explicit. Lifecycle: initiator — system; trigger — any assistant response; observable result — response constrained to approved knowledge and receptionist scope; access — anonymous; failure/recovery — refuse and offer staff connection; continuation — escalate or continue.

FR-21 — Symptom guidance. As a Prospective Patient describing symptoms, I should be told that a dentist must examine me in person, so that I seek proper care. Provenance: explicit. Lifecycle: initiator — visitor; trigger — symptom description; observable result — the examination message is returned; access — anonymous; failure/recovery — escalate to staff; continuation — book an appointment.

FR-22 — Emergency guidance. As a Prospective Patient reporting severe swelling, uncontrolled bleeding, breathing/swallowing difficulty, serious trauma or unconsciousness, I should be advised to seek urgent emergency care immediately, with no delay of care for chat, and escalation when configured. Provenance: explicit. Lifecycle: initiator — visitor; trigger — emergency description; observable result — urgent-care guidance and configured escalation; access — anonymous; failure/recovery — repeat urgent guidance and surface clinic contact; continuation — seek emergency care.

FR-23 — RAG over approved knowledge. As a Prospective Patient, I should receive answers grounded only in approved clinic info, services, education, doctor, hours, policies, location, FAQs, pricing, emergency and pre/post-care, plus live availability and approved education. Provenance: explicit. Lifecycle: initiator — visitor; trigger — question; observable result — grounded answer with source validation; access — anonymous; failure/recovery — unapproved content is filtered and redacted; continuation — continue the conversation.

FR-24 — Unknown-information response. As a Prospective Patient, when information is unknown I should receive "I don't have that information right now. I can connect you with the clinic team.", so that I am never given invented facts. Provenance: explicit. Lifecycle: initiator — system; trigger — retrieval miss; observable result — the exact fallback message plus staff-connection offer; access — anonymous; failure/recovery — escalate to staff; continuation — connect with staff.

FR-25 — No invented facts. As the clinic, I should ensure the assistant never invents price, availability, qualifications, duration, diagnosis or policy. Provenance: explicit. Lifecycle: initiator — system; trigger — any response generation; observable result — only approved facts are stated; access — anonymous; failure/recovery — fallback message; continuation — escalate.

FR-26 — Appointment data collection. As a Prospective Patient, I should provide name, phone, email, preferred date/time, new/existing patient, reason and language, so that the clinic can schedule me correctly. Provenance: explicit. Lifecycle: initiator — visitor; trigger — appointment start; observable result — all fields captured; access — anonymous entry; failure/recovery — validation error with safe message; continuation — proceed to availability.

FR-27 — Appointment state machine. As a Prospective Patient, I should move through GREETING → INTENT → NAME → PHONE → DATE → TIME → REASON → AVAILABILITY → CONFIRM → BOOK → CONFIRMATION → COMPLETE, so that booking is predictable. Provenance: explicit. Lifecycle: initiator — visitor; trigger — each step completion; observable result — progression to the next state; access — anonymous entry; failure/recovery — return to the failed step; continuation — complete the flow.

FR-28 — Summary and explicit confirmation. As a Prospective Patient, I should see a summary of my details and explicitly confirm before submission, so that I never book by accident. Provenance: explicit. Lifecycle: initiator — visitor; trigger — reaching CONFIRM; observable result — summary shown and confirmation required; access — anonymous entry; failure/recovery — edit any step; continuation — BOOK.

FR-29 — Backend owns business logic. As the clinic, I should have the LLM handle language while the backend owns business logic and DB changes, so that state is authoritative and safe. Provenance: explicit. Lifecycle: initiator — system; trigger — any appointment action; observable result — backend validates and writes; access — server-side; failure/recovery — reject invalid transitions; continuation — return a safe error.

FR-30 — AI tools. As a Prospective Patient, I should have Yogesh use the tools clinic info, services, doctor, availability, create/reschedule/cancel appointment, WhatsApp confirmation, lead and staff escalation, so that my request is actually executed. Provenance: explicit. Lifecycle: initiator — visitor; trigger — intent detection; observable result — the correct tool executes against the backend; access — anonymous entry; failure/recovery — safe error and staff escalation; continuation — confirm the outcome.

FR-31 — Appointment statuses. As the clinic, I should track appointments as PENDING, CONFIRMED, RESCHEDULED, CANCELLED, COMPLETED or NO_SHOW, so that the schedule is accurate. Provenance: explicit. Lifecycle: initiator — system and Clinic Admin / Staff; trigger — booking or staff action; observable result — status persisted; access — protected for staff actions; failure/recovery — reject invalid transitions; continuation — notify the patient.

FR-32 — Patient appointment continuity. As an Existing Patient, I should return and view my appointment records with their current status, so that I can manage my care. Provenance: required_inference. Lifecycle: initiator — Existing Patient; trigger — verified sign-in; observable result — records with statuses rendered; access — protected, requires returning verification; failure/recovery — safe authorization error; continuation — reschedule or cancel.

FR-33 — Reschedule. As an Existing Patient, I should reschedule an appointment, so that I can change my plan without calling. Provenance: explicit (reschedule tool) with required_inference continuity. Lifecycle: initiator — Existing Patient; trigger — reschedule action; observable result — status becomes RESCHEDULED and a consent-based WhatsApp confirmation is dispatched; access — protected; failure/recovery — availability conflict offers alternatives; continuation — view the updated record.

FR-34 — Cancel. As an Existing Patient, I should cancel an appointment, so that the slot is released. Provenance: explicit (cancel tool) with required_inference continuity. Lifecycle: initiator — Existing Patient; trigger — cancel action; observable result — status becomes CANCELLED and a consent-based WhatsApp confirmation is dispatched; access — protected; failure/recovery — safe error and staff escalation; continuation — book again if needed.

FR-35 — Database schema. As the engineering team, I should implement patients, appointments, doctors, services, clinic_settings, chat sessions/messages, leads, notifications, admins, audit_logs and knowledge documents, so that all accepted behavior has durable storage. Provenance: explicit. Lifecycle: initiator — system; trigger — migration; observable result — tables created; access — server-side; failure/recovery — migration rollback; continuation — application reads/writes.

FR-36 — Admin dashboard records. As Clinic Admin / Staff, I should manage appointments, leads, chats, requests, inquiries, service interest and analytics, so that I can run the clinic. Provenance: explicit. Lifecycle: initiator — Clinic Admin / Staff; trigger — dashboard load; observable result — records listed; access — protected, requires staff verification; failure/recovery — safe authorization error; continuation — act on a record.

FR-37 — Calendar views. As Clinic Admin / Staff, I should view day, week and month calendars, so that I can plan capacity. Provenance: explicit. Lifecycle: initiator — Clinic Admin / Staff; trigger — view switch; observable result — calendar re-renders for the range; access — protected; failure/recovery — safe error; continuation — act on an appointment.

FR-38 — Appointment actions. As Clinic Admin / Staff, I should confirm, reschedule, cancel, complete, contact and add a note, so that I can manage each appointment end to end. Provenance: explicit. Lifecycle: initiator — Clinic Admin / Staff; trigger — action selection; observable result — status updated, notification dispatched, note stored, audit-logged; access — protected; failure/recovery — safe error; continuation — next record.

FR-39 — CMS without developer. As Clinic Admin / Staff, I should edit clinic info, doctor, services, FAQs, testimonials, gallery, hours, appointment settings, AI knowledge base and WhatsApp templates, with updates live and no developer deploy required. Provenance: explicit. Lifecycle: initiator — Clinic Admin / Staff; trigger — edit and publish; observable result — content live and knowledge re-indexed; access — protected; failure/recovery — validation error or revert; continuation — continue editing.

FR-40 — WhatsApp confirmation. As a Prospective Patient, after confirmation I should receive a consent-based WhatsApp message with patient, doctor and date/time, so that I have a written record. Provenance: explicit. Lifecycle: initiator — backend; trigger — booking confirmation; observable result — WhatsApp message delivered by the provider; access — consent-based; failure/recovery — retry and surface status to staff; continuation — attend the appointment.

FR-41 — WhatsApp reminders. As a Prospective Patient, I should optionally receive 24h and 2h reminders, so that I do not miss my appointment. Provenance: explicit. Lifecycle: initiator — backend; trigger — reminder schedule; observable result — reminder delivered via approved template; access — consent-based; failure/recovery — retry; continuation — attend or reschedule.

FR-42 — Approved templates and secure webhook. As the clinic, I should send only approved WhatsApp templates and receive message events through a secure webhook, so that messaging is compliant and safe. Provenance: explicit. Lifecycle: initiator — provider; trigger — webhook event; observable result — event verified and recorded; access — secured endpoint; failure/recovery — reject unverified payloads; continuation — update notification state.

FR-43 — Security and privacy controls. As the clinic, I should apply HTTPS, encryption in transit and at rest where applicable, secure authentication, RBAC, input validation, rate limiting, CSRF/XSS/SQLi protection, secure cookies, session expiry, audit logs, PII minimization, prompt-injection protection, RAG source validation and secure logging, so that sensitive health data is protected. Provenance: explicit. Lifecycle: initiator — system; trigger — every request; observable result — controls enforced and audited; access — server-side; failure/recovery — reject and log safely; continuation — safe error to the user.

FR-44 — Secrets and PII exposure. As the clinic, I should keep secrets only in the server environment and never expose API keys or sensitive patient data in the frontend or localStorage. Provenance: explicit. Lifecycle: initiator — system; trigger — build and runtime; observable result — no secret or PII in client bundles or storage; access — server-side; failure/recovery — build fails on violation; continuation — deploy.

FR-45 — Consent statement. As a Prospective Patient, I should see "By continuing, you agree that your information may be used to respond to your request and manage your appointment." before submitting information. Provenance: explicit. Lifecycle: initiator — visitor; trigger — form submission; observable result — consent recorded with the submission; access — anonymous; failure/recovery — block submission without consent; continuation — submit.

FR-46 — Legal pages. As a Prospective Patient, I should read the Privacy Policy, Terms and Medical Disclaimer, so that I understand how my information is used and the limits of the service. Provenance: explicit. Lifecycle: initiator — visitor; trigger — page navigation; observable result — legal content rendered; access — anonymous; failure/recovery — safe error; continuation — return to booking.

FR-47 — SEO. As the clinic, I should support local terms such as Dentist near me, Dental clinic [CITY], Dentist [AREA], Root canal [CITY], Dental implant [CITY], Teeth whitening [CITY] and Pediatric dentist [CITY], and implement metadata, OG, canonical, sitemap, robots, breadcrumbs, FAQ and Dentist/LocalBusiness schema, while avoiding unsupported "best" claims. Provenance: explicit. Lifecycle: initiator — system; trigger — crawl or render; observable result — correct metadata and schema emitted; access — public; failure/recovery — validation in CI; continuation — indexing.

FR-48 — Performance targets. As a Prospective Patient, I should experience Lighthouse 90+ overall and SEO 95+, with optimized models, textures, images, fonts, JS/CSS via lazy loading, dynamic imports, code splitting, WebP/AVIF, compressed textures, LOD and GPU-friendly rendering, and heavy 3D loaded after critical content. Provenance: explicit. Lifecycle: initiator — system; trigger — page load; observable result — targets met; access — public; failure/recovery — fallback rendering; continuation — use the site.

FR-49 — Mobile experience. As a Prospective Patient on mobile, I should get a touch-first experience with reduced 3D/fallback, a mobile nav of Home, Services, AI Assistant, Appointment and Contact, and a sticky "Book Appointment". Provenance: explicit. Lifecycle: initiator — visitor; trigger — mobile viewport; observable result — reduced 3D and sticky CTA; access — anonymous; failure/recovery — static fallback; continuation — book.

FR-50 — Accessibility. As a Prospective Patient using assistive technology, I should have keyboard navigation, ARIA, sufficient contrast, visible focus, alt text, reduced motion and an accessible chatbot and forms. Provenance: explicit. Lifecycle: initiator — visitor; trigger — assistive interaction; observable result — all controls operable and announced; access — anonymous; failure/recovery — reduced-motion and fallback paths; continuation — complete the task.

FR-51 — Micro-interactions. As a Prospective Patient, I should see subtle button depth, chatbot pulse, service 3D tilt, section reveals, a tooth loader and short transitions, without overload. Provenance: explicit. Lifecycle: initiator — visitor; trigger — interaction; observable result — restrained motion; access — anonymous; failure/recovery — reduced-motion disables motion; continuation — continue.

FR-52 — Architecture structure. As the engineering team, I should organize the code as app/, components/{3d,animations,chatbot,booking,services,ui}, lib/{ai,rag,db,whatsapp,security}, api/, prisma/, public/{models,textures,images}, hooks/, types/, config/, docs/, with APIs for chat, appointments/availability, leads, WhatsApp webhook, contact and admin auth, validated with Zod/equivalent and returning safe errors with no stack traces. Provenance: explicit. Lifecycle: initiator — engineering team; trigger — implementation; observable result — structure and APIs in place; access — server-side; failure/recovery — validation rejects malformed input; continuation — deploy.

FR-53 — Analytics events. As the clinic, I should capture hero_cta_clicked, service_viewed, chat_opened, chat_started, appointment_started, appointment_completed, whatsapp_clicked, phone_clicked and directions_clicked, while avoiding sensitive health data. Provenance: explicit. Lifecycle: initiator — system; trigger — user action; observable result — event recorded without PII; access — anonymous; failure/recovery — drop the event rather than leak data; continuation — reporting.

FR-54 — Loader and 404. As a Prospective Patient, I should see a short glowing tooth outline with "Preparing your smile experience…" while loading, and on a missing page a friendly 3D tooth with "Oops! This page needs a dental check-up." and a Back to Home action. Provenance: explicit. Lifecycle: initiator — visitor; trigger — load or 404; observable result — loader or 404 experience rendered; access — anonymous; failure/recovery — static fallback; continuation — return home.

FR-55 — Testing. As the engineering team, I should have unit, API, integration and E2E tests for booking, cancellation, rescheduling, chatbot, auth, admin, WhatsApp, RAG, and error/mobile cases. Provenance: explicit. Lifecycle: initiator — engineering team; trigger — CI run; observable result — tests pass; access — CI; failure/recovery — block merge; continuation — deploy.

FR-56 — Deployment artifacts. As the engineering team, I should provide .env.example, Dockerfile, docker-compose.yml, README, migrations, deployment/env docs and CI/CD, and run lint, typecheck, tests and production build with every error fixed and no TODO/FIXME, broken links, console errors, fake APIs, hardcoded secrets or production placeholders. Provenance: explicit. Lifecycle: initiator — engineering team; trigger — release; observable result — clean build and deploy; access — CI/CD; failure/recovery — fail the pipeline; continuation — release.

FR-57 — Deployment targets. As the engineering team, I should deploy the frontend on Vercel, the backend on Cloud Run or AWS, with managed PostgreSQL and Docker. Provenance: explicit. Lifecycle: initiator — engineering team; trigger — deploy; observable result — running production system; access — operations; failure/recovery — rollback; continuation — operate.

FR-58 — Future voice AI. As the clinic, I should be able to add ElevenLabs + Whisper/STT + OpenAI voice on the same backend in English, Hindi and Gujarati as a future capability. Provenance: explicit, future horizon. Lifecycle: initiator — clinic; trigger — future enablement; observable result — voice interaction on the same backend; access — future; failure/recovery — fall back to text chat; continuation — text chat.

FR-59 — Original assets only. As the clinic, I should use the supplied Hariyom logo/mascot image and the user-provided Instagram Reel only as inspiration, never copying the Reel, other clinics or copyrighted assets. Provenance: explicit. Lifecycle: initiator — engineering team; trigger — asset creation; observable result — original assets only; access — internal; failure/recovery — replace non-original asset; continuation — publish.

FR-60 — Design direction compliance. As a Prospective Patient, I should experience a premium, friendly, trustworthy, modern, clean, calm and human interface in the specified palette, avoiding generic hospital templates, excessive glassmorphism/neon, cheap stock photos, clutter and unnecessary motion. Provenance: explicit. Lifecycle: initiator — visitor; trigger — page render; observable result — compliant visual system; access — anonymous; failure/recovery — design review; continuation — use the site.

4. User Personas

Prospective Patient

A visitor exploring Hariyom Dental Clinic, likely carrying some combination of pain, cost worry and fear of the drill. They arrive anonymously, often on a phone, and follow the journey WOW → CURIOUS → TRUST → UNDERSTAND → COMFORTABLE → CHAT WITH AI → BOOK.

Primary goal: Decide whether this clinic is trustworthy and competent, understand what a treatment involves, and book a confirmed appointment without needing to call.

Distinct accepted responsibilities: Browsing the cinematic hero and scroll-driven 3D tooth story; exploring the interactive tooth and reading the Gum, Enamel, Dentin, Root and Nerve educational panels; stepping through the procedure visualizer; reviewing the twelve services and their approved descriptions; reading the doctor profile, Why Hariyom and genuine testimonials; browsing the clinic-owned gallery; conversing with Yogesh in English, Hindi or Gujarati; and completing the appointment flow with explicit confirmation.

Relevant inputs or decisions: Which service they are interested in; whether they are a new or existing patient; their preferred date and time; their reason for visiting; their language; and whether to book, chat, call, or seek emergency care.

Interactions with other accepted participants: Yogesh (the AI receptionist) answers their questions, guides them through the appointment state machine, and escalates to clinic staff when needed. The clinic staff receive their booking, lead or escalation. The WhatsApp provider delivers their confirmation.

Observable success: A confirmed appointment with a summary they explicitly approved, a consent-based WhatsApp confirmation, or — where relevant — clear emergency guidance that tells them not to delay care for chat.

Existing Patient

A patient with an existing record who returns to manage an appointment. They already know the clinic and want efficiency rather than discovery.

Primary goal: Change or cancel an appointment accurately, and get answers about pre/post-care and clinic timings, without staff intervention.

Distinct accepted responsibilities: Verifying their identity to reach their own records; viewing appointment status (PENDING, CONFIRMED, RESCHEDULED, CANCELLED, COMPLETED, NO_SHOW); rescheduling; cancelling; receiving the updated consent-based WhatsApp confirmation; and asking Yogesh about pre/post-care and clinic timings.

Relevant inputs or decisions: Which appointment to change; the new preferred date/time; whether to cancel outright; and whether to escalate to staff.

Interactions with other accepted participants: Yogesh executes the reschedule or cancel through backend tools; the backend validates and writes the state change; the WhatsApp provider delivers the updated confirmation; clinic staff see the updated record in the admin dashboard.

Observable success: An accurately updated appointment with status RESCHEDULED or CANCELLED and a matching WhatsApp confirmation, achieved without calling the clinic.

Clinic Admin / Staff

Clinic staff who operate the schedule and the published clinic knowledge. They are provisioned by clinic administration and verify at a role-appropriate staff login.

Primary goal: Keep the schedule accurate and the published knowledge base current, with full audit logging, without developer help.

Distinct accepted responsibilities: Reviewing appointments, leads, chats, requests, inquiries and service interest with day/week/month calendar views; confirming, rescheduling, cancelling, completing, contacting and adding notes; maintaining clinic info, doctor profile, services, FAQs, testimonials, gallery, hours, appointment settings, AI knowledge base and WhatsApp templates; and publishing changes live.

Relevant inputs or decisions: Which appointment to act on; which content to publish; which testimonials are genuine and approved; which gallery assets are clinic-owned; and which WhatsApp templates are approved.

Interactions with other accepted participants: They receive bookings, leads and escalations generated by Prospective and Existing Patients and by Yogesh; they act on those records; and their CMS edits change what patients see and what Yogesh may answer from.

Observable success: An accurate, up-to-date schedule and knowledge base, published without a code deploy, with every action audit-logged.

5. Core User Flows

Flow 1 — Prospective Patient discovers the clinic and books (Home → Appointment)

1. The Prospective Patient lands on Home anonymously. The cinematic hero renders the headline "Your Smile Deserves Exceptional Care.", the supporting line, the primary CTA "Book an Appointment" and the secondary CTA "Chat with AI Dental Assistant".
2. The visitor scrolls. The 3D tooth begins as a macro enamel view and the scroll-scrubbed camera arc carries it through tooth→rotate→enter→structure→treatment→healthy, ending with the HARIYOM DENTAL CLINIC reveal. Scrolling is never trapped; a fast scroll simply lands on the correct frame.
3. The visitor continues through trust, services preview, treatment journey, Why Hariyom, doctor, AI assistant, education, genuine testimonials, gallery preview, appointment prompt, contact and footer.
4. The visitor opens Services, reviews the twelve approved services with their 3D icons and descriptions, and clicks "Book Appointment" on the relevant service.
5. On Appointment, the visitor enters name, phone, email, preferred date/time, new/existing patient, reason and language. The backend looks up availability.
6. The visitor reviews the summary and explicitly confirms. The consent statement "By continuing, you agree that your information may be used to respond to your request and manage your appointment." is shown and recorded.
7. The backend creates the appointment with status PENDING and returns a confirmation. The WhatsApp provider dispatches a consent-based confirmation containing patient, doctor and date/time.
8. Failure/recovery: if the chosen slot is unavailable, alternatives are offered; if validation fails, a safe message is shown with no stack trace; if WhatsApp delivery fails, the status is surfaced to staff and the patient still sees the confirmed appointment.
9. Continuation: the visitor may open Yogesh for pre-care questions, or return later to Patient Appointments.

Flow 2 — Prospective Patient explores tooth education (Teeth Explorer and Procedure Visualizer)

1. From Home or the nav, the visitor opens Teeth Explorer.
2. The visitor rotates and zooms the tooth, then clicks a hotspot for Gum, Enamel, Dentin, Root or Nerve.
3. A floating hairline-bordered panel anchored to the hotspot opens with a short approved educational explanation, closing with "Educational illustration only — your dentist must examine you in person."
4. The visitor opens Procedure Visualizer and steps through the root canal sequence: problem → cross-section → infection → cleaning → filling → restoration → healthy result. The disclaimer states the illustration is educational and varies by patient, and no AI diagnosis is implied.
5. Failure/recovery: on a low-GPU or reduced-motion device, a still, well-lit frame with the same composition is shown instead of the animation.
6. Continuation: the visitor clicks "Book an Appointment" or opens Yogesh.

Flow 3 — Prospective Patient chats with Yogesh and books (AI Assistant)

1. The visitor opens the floating Yogesh avatar or the AI Assistant page. Yogesh greets: "Hi! I'm Yogesh, Hariyom Dental Clinic's AI Dental Receptionist. How can I help you today?"
2. The visitor types in English, Hindi or Gujarati; Yogesh auto-detects the language and replies in it.
3. The visitor selects the quick action "Book Appointment". Yogesh advances the state machine: GREETING → INTENT → NAME → PHONE → DATE → TIME → REASON → AVAILABILITY → CONFIRM → BOOK → CONFIRMATION → COMPLETE. The LLM handles language; the backend owns business logic and DB changes.
4. Yogesh presents the summary and requires explicit confirmation before booking.
5. The backend creates the appointment and the WhatsApp provider dispatches the consent-based confirmation.
6. Failure/recovery: if the visitor asks something outside approved knowledge, Yogesh replies "I don't have that information right now. I can connect you with the clinic team." and offers staff escalation. If the visitor describes symptoms, Yogesh states that a dentist must examine the patient in person. If the visitor reports severe swelling, uncontrolled bleeding, breathing/swallowing difficulty, serious trauma or unconsciousness, Yogesh advises urgent emergency care, never delays care for chat, and escalates when configured.
7. Continuation: the visitor may ask about treatments, timings or location, or end the conversation.

Flow 4 — Existing Patient reschedules or cancels (Login → Patient Appointments)

1. The Existing Patient opens Login and verifies their identity. Protected appointment state remains unavailable until verification succeeds.
2. On Patient Appointments, the patient sees their records with current status.
3. The patient selects an appointment and chooses reschedule or cancel.
4. For a reschedule, the backend checks availability; for a cancel, the backend validates the transition.
5. The backend writes the new status — RESCHEDULED or CANCELLED — and the WhatsApp provider dispatches the updated consent-based confirmation.
6. Failure/recovery: if the new slot is unavailable, alternatives are offered; if verification fails, a generic safe error is shown with no account enumeration; if the patient prefers, they can escalate to clinic staff.
7. Continuation: the patient may book a new appointment or return to Home.

Flow 5 — Prospective Patient sends an inquiry (Contact)

1. The visitor opens Contact and sees clinic details, hours 10 AM–8 PM, location and directions.
2. The visitor submits an inquiry with the consent statement shown.
3. The backend validates the input and records a lead; clinic staff see it in the Admin Dashboard.
4. Failure/recovery: validation or delivery failure shows a safe message and allows retry.
5. Continuation: the visitor may call, get directions, or book an appointment.

Flow 6 — Clinic Admin / Staff manages the schedule (Admin Login → Admin Dashboard)

1. Clinic staff open Admin Login and verify with their provisioned credentials. Protected operational state remains unavailable until verification succeeds.
2. On Admin Dashboard, staff review appointments, leads, chats, requests, inquiries, service interest and analytics, switching between day, week and month calendar views.
3. Staff select an appointment and confirm, reschedule, cancel, complete, contact or add a note. The backend validates and writes the change, dispatches any required notification, and records an audit log entry.
4. Failure/recovery: an authorization or validation failure returns a safe message; the action is not applied.
5. Continuation: staff move to the next record or open CMS.

Flow 7 — Clinic Admin / Staff updates clinic knowledge (CMS)

1. From Admin Login, staff open CMS.
2. Staff edit clinic info, doctor profile, services, FAQs, testimonials, gallery, hours, appointment settings, AI knowledge base or WhatsApp templates.
3. Staff publish. The change goes live with no developer deploy, and knowledge documents are re-indexed so Yogesh answers from the updated approved content.
4. Failure/recovery: validation errors block publication; staff can revert to the previous version.
5. Continuation: staff verify the change on the public site or in the assistant.

Flow 8 — Prospective Patient reads legal and trust content

1. The visitor opens Trust and reads Dr. Priya Patel's profile, Why Hariyom and genuine testimonials.
2. The visitor opens Gallery and browses clinic-owned assets with lazy loading, opening images in a lightbox.
3. The visitor opens Privacy Policy, Terms and Medical Disclaimer to understand data handling and the non-diagnostic limits of the service.
4. Continuation: the visitor books an appointment or opens Yogesh.

6. Visuals Colors and Theme

Muse and headline: Quiet precision, lit from within — after Jony Ive. The system reads as advanced medical technology that is nonetheless calm, warm and human: one perfectly lit subject on a plain ground, material honesty, and precision that reassures rather than shouts.

Color tokens (light mode):

Proportion: ~70% cool near-white grounds (#F4F7FA page, #FFFFFF surfaces); ~20% deep navy #0E2A5C for type, footer, the doctor section and the booking panel; ~7% turquoise #17B3C9 as the single functional accent (CTAs, hotspot rings, active states, the AI assistant's pulse); ~3% supporting signals used only as tiny coded dots — enamel green #2FA98C for healthy/after states, soft pink #F2C4CE for pediatric and warmth cues. No gradients as decoration; the only gradient allowed is a physical one — a light falloff on the 3D enamel and one soft radial vignette behind the hero subject. Turquoise is never used as body text on white; it appears only as a fill behind navy text or as a 2px rule.

Typography: Headings Fraunces at low optical size and low SOFT axis, weights 300–400 for display and 500 for section labels, tracking −0.02em at display sizes and normal at section sizes, sentence case (all-caps reserved for 11px letterspaced eyebrow labels). Body Inter Tight. Scale 1.25 modular with a display jump: 128 / 88 / 56 / 34 / 22 / 17 / 15. Display sizes use clamp(40px, 9vw, 128px) for the hero and clamp(30px, 5vw, 56px) for section heads. Body 17px/1.6 desktop, 16px/1.65 mobile, measure capped at 68ch. Eyebrow labels 11px, +0.14em tracking, uppercase, Inter Tight 600.

Shape language: Continuous-curve softness — cards and panels use 20–28px radii with a single consistent corner rhythm. The tooth is the only truly organic form on the page, so UI chrome stays quiet and geometric by comparison. No blobs, no stickers, no sketched arrows. Depth comes from light, not shadows: a 1px hairline in #E2E9F1 plus one very soft, wide, low-opacity shadow 0 24px 60px -32px rgba(14,42,92,0.28) that reads as a studio floor shadow under the subject. Dividers are hairlines, never boxes.

Spacing rhythm: Max content 1200px; gutters 24/40/72px at 375/768/1280. Section vertical rhythm on a 8px base with 96–160px section padding at desktop and 56–88px on mobile.

Imagery style: One subject, one light. The hero and interactive tooth are a real-time 3D molar rendered with physically-based enamel (subtle subsurface, roughness ~0.18, clearcoat) on a plain cool-white cyclorama, lit by a key + rim + soft fill exactly as a product studio would light a phone. No stock people, no smiling-model photography, no clip art. Photography is permitted only as clinic-owned documentary — the real operatory, the real chair, Dr. Priya Patel's real portrait, real before/after with patient consent — treated monochrome-cool and generously cropped. Service icons are original low-poly 3D renders of instruments (probe, scaler, implant screw, aligner, whitening tray) on the same plain ground, so the whole site looks like one photoshoot.

Forbidden: Any blue–indigo SaaS accent (#2563EB, #4F46E5, #6366F1) on white, or gradient-blob hero backgrounds; Inter, Roboto, Poppins, Lato, Open Sans or system-ui for headings; glassmorphism panels, neon glows, particle confetti or animated gradient meshes; a grid of identical hover-lift cards with identical shadows; stock photography of models with perfect teeth or any imagery not owned by the clinic; pinned scroll-jacking that prevents scrolling past the 3D hero; diagnostic language, price figures, credentials, testimonials or "best in city" claims that are not clinic-verified; decorative motion on mobile beyond the assistant pulse and one reveal.

7. Signature Design Concept

"The first frame is a material, not a tooth."

The public entry is a split hero that could not be mistaken for SaaS. The left five columns hold the headline "Your Smile Deserves Exceptional Care." set in Fraunces 300 at clamp(40px, 9vw, 128px), stacked over three lines, with "Exceptional Care" in deep navy #0E2A5C and the rest in near-black #0B1B33 — no gradient text. Beneath it, a 68ch-max supporting line in Inter Tight 17px #5B7089, then a horizontal row of two controls: a solid navy pill "Book an Appointment" with a 1px turquoise top-edge highlight, and a text-weight "Chat with AI Dental Assistant" with a small animated turquoise dot.

The right seven columns are the 3D tooth, bleeding off the top-right edge. At load it is a macro enamel crop — an abstract, jewel-like surface with visible light falloff and a moving specular highlight — so the visitor sees a material before they see a tooth. A thin vertical hairline at the 5/7 boundary is the only chrome. Below the fold-line, a scroll cue is a 1px navy line that draws itself downward. No badge rows, no logo strip, no gradient blob, no centred stack.

As the visitor scrolls, the macro crop resolves into a whole tooth and the scroll-scrubbed camera arc carries it through rotation, cross-section (enamel → dentin → pulp) and a healthy state, with the DOM section titles cross-fading in step. Scrolling is never trapped; a fast scroll simply lands on the right frame. The concept recomposes only accepted content, states and controls — it introduces no new behaviour, page or destination.

8. Interaction Model & Motion Direction

Interaction Model: Animated Motion Tempo: restrained Hero Dimensionality: layered_2d

Landing Hero Motion Brief

• Focal subject: A real-time 3D molar rendered with physically-based enamel on a plain cool-white cyclorama, lit by a key + rim + soft fill — the single perfectly lit subject of the composition.
• Input → transformation → outcome thesis: Scroll input drives a GSAP ScrollTrigger scrubbed timeline that transforms the camera from a macro enamel crop into a whole tooth, then around and inside it through cross-section to a healthy state, and finally reveals HARIYOM DENTAL CLINIC beside the booking CTA. The visitor's own scrolling is the only driver; nothing plays on a timer and nothing blocks the page.
• Motion vocabulary: One hero gesture — a scroll-linked camera arc. Reveals are a 12px rise plus opacity over 480ms with a soft ease-out. Nothing bounces. The only looping motion is the AI assistant's slow 3.2s breathing pulse and a subtle enamel specular drift. Hotspots scale 1→1.06 on hover.
• Composed first frame: Left five columns of type, right seven columns of abstract macro enamel with a moving specular highlight, a hairline at the boundary, and a 1px navy scroll cue drawing itself downward below the fold-line.
• Reduced-motion state: A still, well-lit frame with the same composition — the macro enamel crop, the headline, both CTAs and the scroll cue — with no camera arc, no specular drift and no assistant pulse beyond a static ring.

9. Non-Functional Requirements

NFR-1 — Performance. Lighthouse 90+ overall and SEO 95+. Optimize models, textures, images, fonts, JS and CSS using lazy loading, dynamic imports, code splitting, WebP/AVIF, compressed textures, LOD and GPU-friendly rendering. Load heavy 3D after critical content. Provenance: explicit. Rationale: the 3D hero must never cost the clinic its conversion path.

NFR-2 — Animation must not block. Animation must never block scrolling or hurt performance; a low-GPU/mobile fallback and a reduced-motion path are mandatory. Provenance: explicit.

NFR-3 — Mobile-first. Touch-first UI with reduced 3D/fallback; mobile nav of Home, Services, AI Assistant, Appointment and Contact; sticky "Book Appointment". Provenance: explicit.

NFR-4 — Accessibility. Keyboard navigation, ARIA, sufficient contrast, visible focus, alt text, reduced motion, and an accessible chatbot and forms. Provenance: explicit.

NFR-5 — Security. HTTPS everywhere; encryption in transit and at rest where applicable; secure authentication; RBAC; input validation; rate limiting; CSRF, XSS and SQLi protection; secure cookies; session expiry; audit logs; PII minimization; prompt-injection protection; RAG source validation; secure logging. Provenance: explicit.

NFR-6 — Secrets and PII. Secrets only in the server environment; never expose API keys or sensitive patient data in the frontend or localStorage. Provenance: explicit.

NFR-7 — Input validation and safe errors. Validate with Zod or equivalent; return safe errors with no stack traces. Provenance: explicit.

NFR-8 — Analytics privacy. Capture only the named events and never track or report sensitive health data or PII. Provenance: explicit.

NFR-9 — SEO. Metadata, OG tags, canonical URLs, sitemap, robots.txt, breadcrumbs, FAQ schema and Dentist/LocalBusiness schema; support the listed local search terms; avoid unsupported "best" claims. Provenance: explicit.

NFR-10 — Content integrity. Never invent credentials, testimonials, prices or claims; use only approved clinic data; testimonials must be genuine clinic-provided or clearly marked admin placeholders; gallery must use clinic-owned assets. Provenance: explicit.

NFR-11 — Build hygiene. No TODO/FIXME, broken links, console errors, fake APIs, hardcoded secrets or production placeholders; run lint, typecheck, tests and production build and fix every error. Provenance: explicit.

NFR-12 — CMS autonomy. CMS updates must go live with no developer intervention. Provenance: explicit.

NFR-13 — Readable text and controls. Headlines, wordmarks, labels, numbers, card text and controls stay entirely inside the viewport and their container at 375px, 768px and 1280px, wrapping or scaling to fit, with no other element covering them. Provenance: explicit design constraint.

10. Tech Stack

• Frontend: Next.js + React + TypeScript + Tailwind CSS. Provenance: explicit.
• 3D and animation: Three.js, React Three Fiber, Drei, GSAP and/or Framer Motion; optimized GLB/GLTF with Draco/Meshopt compression; realistic materials; studio/rim lighting. Provenance: explicit.
• Backend: Next.js API routes or Python FastAPI. Provenance: explicit.
• LLM: OpenAI API, with optional LangChain/LangGraph. Provenance: explicit.
• Database: PostgreSQL with Prisma ORM. Provenance: explicit.
• Vector store: pgvector or Qdrant. Provenance: explicit.
• Embeddings: OpenAI. Provenance: explicit.
• Cache: Redis. Provenance: explicit.
• Storage: S3-compatible. Provenance: explicit.
• WhatsApp: Meta WhatsApp Business API or an approved provider. Provenance: explicit.
• Deployment: Vercel (frontend), Cloud Run or AWS (backend), managed PostgreSQL, Docker. Provenance: explicit.
• Project structure: app/, components/{3d,animations,chatbot,booking,services,ui}, lib/{ai,rag,db,whatsapp,security}, api/, prisma/, public/{models,textures,images}, hooks/, types/, config/, docs/. Provenance: explicit.
• Future voice: ElevenLabs + Whisper/STT + OpenAI on the same backend, in English, Hindi and Gujarati. Provenance: explicit, future horizon.

11. Assumptions and Constraints

Assumptions

• A-1: The clinic supplies verified qualifications, experience and practice areas for Dr. Priya Patel; until then the profile shows a photo placeholder and only verified content. Label: assumption, consistent with the explicit "never invent credentials" constraint.
• A-2: Testimonials are supplied by the clinic; until then, clearly marked admin placeholders are used with admin approval. Label: assumption.
• A-3: Gallery assets are clinic-owned; no third-party imagery is used. Label: assumption.
• A-4: The clinic supplies approved service descriptions, FAQs, policies, location, pricing, emergency and pre/post-care content for the knowledge base. Label: assumption.
• A-5: The clinic supplies approved WhatsApp message templates and configures the provider. Label: assumption.
• A-6: Clinic staff are provisioned by clinic administration; self-service staff registration is not offered. Label: assumption, consistent with the required-inference provisioning boundary.
• A-7: [CITY] and [AREA] placeholders in SEO terms are resolved from clinic settings at build/render time. Label: assumption.
• A-8: The supplied Hariyom logo/mascot image and the Instagram Reel are inspiration only; all shipped assets are original or clinic-owned. Label: assumption, consistent with the explicit constraint.

Constraints

• C-1: Use the supplied Hariyom logo/mascot image and the user-provided Instagram Reel only as inspiration; do not copy the Reel, other clinics or copyrighted assets.
• C-2: Never diagnose; the interactive tooth and procedure visualizer must never diagnose or imply AI diagnosis.
• C-3: Clearly state that procedure illustrations are educational and vary by patient.
• C-4: The AI is a receptionist/educational assistant, not a doctor: never diagnose, prescribe medicine or dosage, guarantee outcomes, replace dental consultation, invent facts or claim certainty.
• C-5: For symptoms, say a dentist must examine the patient.
• C-6: For severe swelling, uncontrolled bleeding, breathing/swallowing difficulty, serious trauma or unconsciousness: advise urgent emergency care, never delay care for chat, and escalate when configured.
• C-7: Answer only from approved knowledge, live availability and approved education; never invent price, availability, qualifications, duration, diagnosis or policy.
• C-8: If information is unknown, respond "I don't have that information right now. I can connect you with the clinic team."
• C-9: Use only approved clinic data for services; never invent credentials, testimonials, prices or claims.
• C-10: Testimonials must be genuine clinic-provided; otherwise use admin placeholders.
• C-11: Gallery must use clinic-owned assets with lightbox and lazy loading.
• C-12: Avoid unsupported "best" claims in SEO content.
• C-13: Secrets only in the server environment; never expose API keys or sensitive patient data in the frontend or localStorage.
• C-14: Treat health data as sensitive; apply HTTPS, encryption in transit and at rest where applicable, secure authentication, RBAC, input validation, rate limiting, CSRF/XSS/SQLi protection, secure cookies, session expiry, audit logs, PII minimization, prompt-injection protection, RAG source validation and secure logging.
• C-15: Consent statement required: "By continuing, you agree that your information may be used to respond to your request and manage your appointment."
• C-16: Include Privacy Policy, Terms and Medical Disclaimer.
• C-17: Never let animation block scrolling or hurt performance; provide low-GPU/mobile fallback and reduced motion.
• C-18: Load heavy 3D after critical content; mobile must be touch-first with reduced 3D/fallback.
• C-19: Avoid generic hospital templates, excessive glassmorphism/neon, cheap stock photos, clutter and unnecessary motion.
• C-20: Never overload micro-interactions.
• C-21: No TODO/FIXME, broken links, console errors, fake APIs, hardcoded secrets or production placeholders.
• C-22: Run lint, typecheck, tests and production build; fix every error.
• C-23: Validate inputs with Zod or equivalent; return safe errors with no stack traces.
• C-24: Avoid sensitive health data in analytics events.
• C-25: CMS updates must need no developer.
• C-26: WhatsApp messages must be consent-based and use approved templates with a secure webhook.
• C-27: Future voice capability (ElevenLabs + Whisper/STT + OpenAI) must run on the same backend in English, Hindi and Gujarati.
• C-28: The generic indigo/blue-on-white SaaS template is forbidden for this project.

Future horizon (not current acceptance)

• F-1: Voice interaction via ElevenLabs + Whisper/STT + OpenAI on the same backend, in English, Hindi and Gujarati. It is excluded from current pages and acceptance and must not appear as a current capability.

12. Glossary

• Hariyom Dental Clinic — The single-doctor, family-run dental practice this product serves, led by Dr. Priya Patel, open 10 AM–8 PM.
• Yogesh — The AI Dental Receptionist: a multilingual, non-diagnostic assistant that answers from approved knowledge and executes appointment tools through the backend.
• RAG — Retrieval-Augmented Generation: answering only from approved, validated knowledge sources plus live availability and approved education.
• Approved knowledge — Clinic information, services, education, doctor profile, hours, policies, location, FAQs, pricing, emergency and pre/post-care content published through the CMS.
• Appointment state machine — GREETING → INTENT → NAME → PHONE → DATE → TIME → REASON → AVAILABILITY → CONFIRM → BOOK → CONFIRMATION → COMPLETE.
• Appointment statuses — PENDING, CONFIRMED, RESCHEDULED, CANCELLED, COMPLETED, NO_SHOW.
• Hotspot — A clickable anatomical region on the interactive tooth: Gum, Enamel, Dentin, Root, Nerve.
• Procedure visualizer — The educational step-through of a procedure sequence, such as root canal problem → cross-section → infection → cleaning → filling → restoration → healthy result.
• Consent statement — "By continuing, you agree that your information may be used to respond to your request and manage your appointment."
• Staff escalation — Handing a conversation or request to clinic staff when the assistant cannot resolve it or when an emergency is reported.
• Low-GPU/mobile fallback — The reduced-poly, static or SVG rendering path used when the device cannot sustain the full 3D experience.
• Reduced motion — The prefers-reduced-motion path that renders a still, well-lit frame with the same composition instead of animation.
• CMS — The protected content-management surface where staff edit clinic info, doctor, services, FAQs, testimonials, gallery, hours, appointment settings, AI knowledge base and WhatsApp templates without a developer deploy.
• Admin Dashboard — The protected operational surface for appointments, leads, chats, requests, inquiries, service interest and analytics, with day/week/month calendar views and confirm/reschedule/cancel/complete/contact/note actions.
• Lead — A recorded inquiry or service-interest submission from a visitor, visible to clinic staff.
• Audit log — The durable record of staff and system actions on protected state.