Page 1 of 39

System Requirements Document

MASAR — Physical Therapy & Therapeutic Nutrition Center Website

1. Introduction

Page 2 of 39

1.0 Source Content Inventory

This SRD is derived from the authoritative user-supplied source document MASAR Master Project README (chat_media/131dcc45-c665-4211-a4be-862754788077/0b7d12bc_MASAR_Master_README.txt, uploaded by the user, message 0de38ccd-a3d2-4da8-b3e1-b7c92d80b4f0, created 2026-10-01T16:35:55Z). The README is the content source, domain context, and feature reference for this project; the requirements below are its canonical translation. The following named items are carried from that source and are the downstream source of truth:

Project name: MASAR — Physical Therapy & Therapeutic Nutrition Center Website (project slug: file-job).
Product identity: a bilingual (Arabic/English) public marketing and service-discovery website for a physical therapy and therapeutic nutrition center, backed by a secured API, a relational database, and an authenticated administration dashboard.
Hero concept copy: "Move Better. Live Better." with supporting CMS-editable text.
Primary CTA label: "Explore Services". Secondary CTA label: "Chat on WhatsApp".
Discovery section title: "What Brings You Here?" with the six selectable options listed in §3.4.
Guided flow name: "Find Your Path" with the three steps and body-area options listed in §3.5.
Treatment Philosophy journey: Assessment → Understanding Your Needs → Personalized Care → Progress → Better Movement.
Doctor: Dr. Waleed (optional approved section "A message from Dr. Waleed").
"Why MASAR" pillars: Personalized Care, Professional Approach, Integrated Services, Human Connection.
"Before Your First Visit" topics: what to expect, what to bring, how the first interaction works, how to contact MASAR, location, working hours.
Initial example services: Physical Therapy, Back & Neck Care, Sports Rehabilitation, Manual Therapy, Therapeutic Nutrition, Specialized Rehabilitation Programs.
Public pages: Home, Services, Service Details, About MASAR, Doctor Profile, Find Your Path, FAQ, Contact, Privacy/Legal pages where required.
Admin structure: /admin → Login → Dashboard → Content (Homepage, Services, Doctor Profile, FAQs, Testimonials, Pages) → Media → Settings (Contact, WhatsApp, Phone, Working Hours, Social Links, SEO, General) → Navigation → Analytics → Audit Logs.
Admin media tree: Media (Logo, Doctor Photo, Clinic Images, Service Images, Gallery) and Settings (Contact, WhatsApp, Phone, Working Hours, Social Media → Instagram/Facebook/TikTok, SEO, General).
Social platforms in V1: Instagram, Facebook, TikTok.
Optional assistant name: MASAR Assistant (V1.5), explicitly not an "AI Doctor".
Deployment targets: Cloudflare Pages (frontend), Render (backend), Neon PostgreSQL (database).
Brand/visual direction: calm, clean, professional, human, modern, trustworthy, premium, comfortable, clinical but warm; Deep Teal primary, Natural Green secondary, Soft Sage accent, Warm White/Off-white background, Charcoal primary text, Muted Gray secondary text.
Signature concept: "A quiet, confident digital space for movement, recovery and care" resolving as Calm → Clear → Human → Professional → Trustworthy.

Facts not present in the source document (for example, the clinic's real address, phone number, WhatsApp number, working hours, official social URLs, and the doctor's approved credentials) are unverified and must be supplied by the clinic through the CMS; they must never be invented.

Page 3 of 39

1.1 Purpose

This System Requirements Document (SRD) defines the complete requirements for MASAR, a professional website for a physical therapy and therapeutic nutrition center, together with a secure content administration system. It translates the MASAR Master Project README into canonical, testable requirements covering the public website, the administrative CMS, security, safety, accessibility, SEO, performance, and deployment.

1.2 Product Statement

MASAR is a calm, premium, human-centered digital experience for a physical therapy and therapeutic nutrition center. The public website helps visitors understand MASAR quickly, explore services, learn about the doctor and treatment philosophy, find the most relevant service, read trusted educational content, contact MASAR (WhatsApp/phone), and find the clinic location and working hours. A secure administration system lets authorized staff manage website content without touching the database directly.

1.3 Guiding Principles

Build for today's needs, architect for tomorrow's growth.
Do not build unnecessary features merely because the architecture can support them.
Do not build a fragile website that would require a full rebuild as MASAR grows.
The user experience stays simple even when the internal architecture is sophisticated.
The complexity belongs underneath the interface.

1.4 Scope Summary

V1 (Required): Arabic/English, RTL/LTR, responsive premium design, public pages, Find Your Path, WhatsApp, admin authentication/dashboard/CMS, Draft/Preview/Publish, media management, SEO basics, accessibility, audit logs, secure architecture, production deployment.
V1.5: Interactive body map, testimonials, clinic gallery, lightweight analytics, MASAR Assistant, revision history.
V2: Patient accounts, appointments, patient portal, treatment plans, progress tracking, nutrition plans, notifications, payments if required.

Page 4 of 39

2. System Overview

2.1 Product Shape

MASAR V1 is a bilingual (Arabic/English) public marketing and service-discovery website backed by a secured API and a relational database, plus an authenticated administration dashboard that manages all clinic content and media through a Draft → Preview → Publish workflow. There is no online appointment booking in V1 and no public user accounts in V1. WhatsApp is the primary conversion path; phone call is the secondary conversion path.

2.2 Public/Admin/AI Boundaries

Public: Public Website → Public API → Application → Domain → Infrastructure → Database / Storage / External Services.
Admin: Admin UI → Authenticated API → Authorization → Application → Domain → Infrastructure.
AI (optional): Assistant UI → Assistant Application Service → Approved MASAR Content → AssistantProvider → AI Provider. The AI provider must never directly access the production database.

2.3 Production Architecture (V1)

Browser → Cloudflare Pages (Frontend) --HTTPS--> Render (Backend/API) → Neon PostgreSQL

Supporting infrastructure:

Render Backend
  ├── MediaStorage abstraction → Object Storage / CDN
  ├── WhatsApp integration
  ├── Analytics provider
 \x20\xe2\x94\x94── Optional AssistantProvider

Page 5 of 39

2.4 Layered Architecture

Presentation → Application → Domain → Infrastructure

Dependencies point inward. Domain must not directly depend on framework, database implementation, cloud provider, or AI vendor.

3. Functional Requirements (User Stories)

3.1 Localization & Multilingual Content

As a visitor, I want the website to fully support Arabic, so that I can consume all content in Arabic.
As a visitor, I want the website to fully support English, so that I can consume all content in English.
As a visitor, I want RTL (right-to-left) layout support, so that the Arabic interface is correctly mirrored, ordered, and readable.
As a visitor, I want LTR (left-to-right) layout support, so that the English interface reads naturally and correctly.
As a visitor, I want RTL / LTR behavior to be correct across the whole application (not only on some pages), so that switching direction never breaks layout, alignment, or logic.
As a visitor, I want a language switcher, so that I can change the interface language at any point.
As a visitor, I want mixed Arabic/English content handled correctly (including punctuation, numbers, dates, phone numbers, and URLs), so that bilingual content is presented correctly.
As a visitor, I want Arabic treated as a first-class language (not a translated version of the English UI), so that typography, line height, letter spacing, responsive sizing, and text wrapping are appropriate for Arabic.
As a visitor, I want a localized navigation, so that menu and navigation labels appear in my selected language.
As a visitor, I want localized metadata (titles, descriptions, slugs, alternates), so that search engines and link previews reflect my language.

Page 6 of 39

3.2 Global Navigation & Layout

As a visitor, I want a header on the site, so that I can access primary navigation at all times.
As a visitor, I want the header to contain the MASAR logo, Home, Services, About, Find Your Path, Contact, Language Switcher, and WhatsApp CTA, so that all key destinations and actions are reachable.
As a visitor, I want the header to slightly compact with a smooth transition and subtle border/shadow on scroll, so that navigation stays available without distracting from content.
As a visitor, I want a mobile header containing the logo, menu, and language switcher where appropriate, so that navigation works well on mobile.
As a visitor, I want a mobile menu containing Home, Services, About, Find Your Path, FAQ, Contact, and WhatsApp, so that all key destinations are reachable on mobile.
As a visitor, I want a dedicated menu control on mobile, so that I can open and close the site navigation cleanly.
As a visitor, I want a responsive navigation, so that the site is usable across device sizes.
As a visitor, I want a footer that includes a MASAR description, explore links, a dynamic service list, contact details, working hours, legal links, social links, and copyright, so that I can find secondary information and links.
As a visitor, I want a final calm CTA before the footer, so that there is a clear closing action.
As a visitor, I want the footer to feel rich but clean, so that it is informative without being cluttered.

3.3 Homepage

As a visitor, I want a Hero section, so that I immediately understand MASAR's purpose.
As a visitor, I want the hero to present the concept "Move Better. Live Better." with supporting text, so that the value proposition is clear, and I want the hero copy to be CMS-editable and not hardcoded.
As a visitor, I want a primary CTA "Explore Services", so that I can move toward exploring services.
As a visitor, I want a secondary CTA "Chat on WhatsApp", so that I can immediately contact MASAR.
As a visitor, I want a "What Brings You Here?" section, so that I can identify my general goal and navigate to relevant content.
As a visitor, I want a Find Your Path section on the homepage, so that I can start guided service discovery.
As a visitor, I want a Treatment Philosophy section, so that I understand the MASAR care philosophy.
As a visitor, I want a Doctor section, so that I can learn about the doctor and treatment approach.
As a visitor, I want a "Why MASAR" section, so that I understand the clinic's factual differentiators.
As a visitor, I want a "Before Your First Visit" section, so that I know what to expect before my first visit.
As a visitor, I want an FAQ preview where useful on the homepage, so that I can get quick answers.
As a visitor, I want a Contact CTA on the homepage, so that I can reach MASAR easily.
As a visitor, I want social media icons where appropriate on the homepage, so that I can reach official social channels.

Page 7 of 39

3.4 "What Brings You Here?" (Discovery Section)

As a visitor, I want the selectable option "I'm experiencing pain", so that I can indicate my general goal.
As a visitor, I want the selectable option "I have a sports injury", so that I can indicate my general goal.
As a visitor, I want the selectable option "I need rehabilitation", so that I can indicate my general goal.
As a visitor, I want the selectable option "I'm interested in therapeutic nutrition", so that I can indicate my general goal.
As a visitor, I want the selectable option "I want to improve my movement", so that I can indicate my general goal.
As a visitor, I want the selectable option "I'm not sure where to start", so that I am still guided even without a clear goal.
As a visitor, I want this section to function as a navigation/discovery experience (not a diagnostic system), so that I am guided to relevant content without receiving a diagnosis.

3.5 Find Your Path

As a visitor, I want a guided multi-step flow that moves from (1) "What are you looking for?" → (2) "Where is the issue or goal?" → (3) "What best describes your situation?" → Relevant MASAR Services, so that I can be guided to relevant services.
As a visitor, I want to select the body area Neck, so that results reflect my location of concern.
As a visitor, I want to select the body area Shoulder, so that results reflect my location of concern.
As a visitor, I want to select the body area Back, so that results reflect my location of concern.
As a visitor, I want to select the body area Hip, so that results reflect my location of concern.
As a visitor, I want to select the body area Knee, so that results reflect my location of concern.
As a visitor, I want to select the body area Ankle, so that results reflect my location of concern.
As a visitor, I want to select the body area Other, so that I can proceed when none of the listed areas fit.
As a visitor, I want the flow to suggest relevant services at the end, so that I know where to go next.
As a visitor, I want a clear statement that the tool is for general guidance and service discovery only and does not provide a medical diagnosis, so that I understand its limitations.
As a visitor, I want the Find Your Path interaction to be mobile-friendly, so that it works well on phones.
As a visitor, I want the Find Your Path interaction to be keyboard accessible, so that I can complete it without a mouse.

Page 8 of 39

3.6 Treatment Philosophy

As a visitor, I want the care philosophy presented as a simple journey: Assessment → Understanding Your Needs → Personalized Care → Progress → Better Movement, so that I understand the care approach.
As a visitor, I want this journey to be presented visually but calmly, so that it is clear without being overwhelming.
As a visitor, I want the section to not promise specific outcomes, so that the content remains truthful.

3.7 Doctor Section / Doctor Profile

As a visitor, I want a Doctor Profile page, so that I can learn about the doctor.
As a visitor, I want the profile to include only real clinic-approved information: real photo, name, professional title, qualifications, specialties, professional biography, treatment philosophy, and approved credentials, so that I can trust the information.
As a visitor, I want an optional "A message from Dr. Waleed" section where approved, so that the doctor can address visitors directly.
As a visitor, I want the profile to contain no invented certifications, awards, experience years, statistics, publications, hospital affiliations, or testimonials, so that I am never misled.
As a visitor, I want the doctor profile and its image to be CMS-managed, so that information stays current.
As a visitor, I want the doctor profile available in Arabic and English, so that I can read it in my language.

3.8 Why MASAR

As a visitor, I want a "Why MASAR" section covering Personalized Care, so that I understand one differentiator.
As a visitor, I want a "Why MASAR" section covering Professional Approach, so that I understand one differentiator.
As a visitor, I want a "Why MASAR" section covering Integrated Services, so that I understand one differentiator.
As a visitor, I want a "Why MASAR" section covering Human Connection, so that I understand one differentiator.
As a visitor, I want the section to use only factual differentiators and avoid unsupported claims such as "best clinic", "#1 center", "guaranteed results", or "highest success rate", so that I am not misled.

Page 9 of 39

3.9 Before Your First Visit

As a visitor, I want a "Before Your First Visit" section explaining what to expect, so that I know what will happen.
As a visitor, I want it to explain what to bring, so that I arrive prepared.
As a visitor, I want it to explain how the first interaction works, so that I know the process.
As a visitor, I want it to explain how to contact MASAR, so that I can reach the clinic.
As a visitor, I want it to show the location, so that I can find the clinic.
As a visitor, I want it to show the working hours, so that I know when to visit.

Page 10 of 39

3.10 Services (Listing & Detail)

As a visitor, I want a Services page listing available services, so that I can explore what MASAR offers.
As a visitor, I want the service list to be CMS-driven, so that it reflects clinic-approved content.
As a visitor, I want an initial set of example services including Physical Therapy, so that I understand the type of content offered.
As a visitor, I want an initial set of example services including Back & Neck Care, so that I understand the type of content offered.
As a visitor, I want an initial set of example services including Sports Rehabilitation, so that I understand the type of content offered.
As a visitor, I want an initial set of example services including Manual Therapy, so that I understand the type of content offered.
As a visitor, I want an initial set of example services including Therapeutic Nutrition, so that I understand the type of content offered.
As a visitor, I want an initial set of example services including Specialized Rehabilitation Programs, so that I understand the type of content offered.
As a visitor, I understand that final services must come from CMS/clinic-approved content.
As a visitor, I want a Service Detail page, so that I can learn about a specific service.
As a visitor, I want the Service Detail page structured as: Breadcrumb → Hero → What This Service Is → Who It May Be Relevant For → What The Process May Look Like → What To Expect → Related Services → FAQ → WhatsApp CTA → Contact, so that I can understand the service and act.
As a visitor, I want the Service Detail page to avoid guaranteed results, medical diagnosis, unsupported claims, and fear-based marketing, so that the content is trustworthy.
As a visitor, I want each service to support the field title_ar, so that services are bilingual.
As a visitor, I want each service to support the field title_en, so that services are bilingual.
As a visitor, I want each service to support short_description_ar and short_description_en, so that summaries are bilingual.
As a visitor, I want each service to support detailed_description_ar and detailed_description_en, so that detailed content is bilingual.
As a visitor, I want each service to support hero_image and gallery, so that visual content is managed.
As a visitor, I want each service to support symptoms_or_goals_ar and symptoms_or_goals_en, so that relevance cues are bilingual.
As a visitor, I want each service to support related_services, so that I can discover connected services.
As a visitor, I want each service to support faqs (service-specific FAQs), so that answers are relevant to the service.
As a visitor, I want each service to support seo_title_ar and seo_title_en, so that services are searchable in both languages.
As a visitor, I want each service to support seo_description_ar and seo_description_en, so that services are discoverable in both languages.
As a visitor, I want each service to support slug_ar and slug_en, so that localized URLs are clean.
As a visitor, I want each service to support display_order, so that ordering is controlled.
As a visitor, I want each service to support published, so that only approved services appear.
As a visitor, I want a contextual WhatsApp CTA on service pages, so that I can start a relevant conversation.

Page 11 of 39

3.11 Testimonials (V1.5)

As a visitor, I want to see real testimonials with appropriate consent where present, so that I can consider others' experiences.
As an administrator, I want to add testimonials, so that I can publish new approved testimonials.
As an administrator, I want to edit testimonials, so that I can correct content.
As an administrator, I want to hide testimonials, so that I can temporarily remove them.
As an administrator, I want to delete testimonials, so that I can remove them permanently.
As an administrator, I want to reorder testimonials, so that I can control their presentation order.
As a visitor, I want the site to never display fabricated testimonials, so that I can trust what I read.

3.12 Gallery (V1.5)

As a visitor, I want a gallery with the category Clinic, so that I can see the clinic environment.
As a visitor, I want a gallery with the category Equipment, so that I can see the equipment.
As a visitor, I want a gallery with the category Environment, so that I can see the environment.
As a visitor, I want a gallery with the category Doctor, so that I can see the doctor.
As a visitor, I want a gallery with the category Nutrition, so that I can see nutrition-related imagery.
As a visitor, I want a gallery with the category Activities, so that I can see clinic activities.
As an administrator, I want to upload, replace, delete, reorder, and hide gallery images, so that I can manage visual content.
As an administrator, I want to add Arabic alt text, so that images are accessible in Arabic.
As an administrator, I want to add English alt text, so that images are accessible in English.
As an administrator, I want to add metadata, so that images are organized.
As a visitor, I want gallery images to be optimized, so that pages load quickly.

Page 12 of 39

3.13 FAQ

As a visitor, I want an FAQ page, so that I can read common questions and answers.
As a visitor, I want FAQs to be CMS-driven, so that answers are current.
As a visitor, I want FAQs to support Global scope, so that site-wide questions are shown.
As a visitor, I want FAQs to support Service-specific scope, so that answers are relevant in service context.
As an administrator, I want FAQ fields including question_ar, question_en, answer_ar, answer_en, category, display_order, and published, so that FAQs are bilingual, categorized, ordered, and publishable.

3.14 Contact

As a visitor, I want a Contact page, so that I can reach MASAR.
As a visitor, I want contact information to include WhatsApp, so that I can message the clinic.
As a visitor, I want contact information to include Phone, so that I can call the clinic.
As a visitor, I want contact information to include Location, so that I know where to go.
As a visitor, I want contact information to include Working Hours, so that I know when to visit.
As a visitor, I want contact information to include Google Maps / Directions, so that I can navigate to the clinic.
As a visitor, I want contact information to include Official Social Links, so that I can reach official channels.
As a visitor, I want contact information to come from CMS/site settings and not be hardcoded in UI components, so that it stays accurate and updatable.

3.15 WhatsApp System

As a visitor, I want WhatsApp to be the primary conversion mechanism, so that I can contact MASAR easily.
As a visitor, I want contextual WhatsApp messages, so that the message reflects the context (e.g., "Hello MASAR, I would like to know more about Sports Rehabilitation." or "Hello MASAR, I would like to know more about Therapeutic Nutrition.").
As a visitor, I want WhatsApp messages to support service context, so that my intent is preserved.
As a visitor, I want WhatsApp messages to support language, so that my language is preserved.
As a visitor, I want WhatsApp messages to support general contact context, so that a generic message is also possible.
As a system owner, I want WhatsApp URL/message generation centralized conceptually through a WhatsAppMessageBuilder (inputs: context, service, language → safe WhatsApp URL), so that URL logic is not duplicated throughout components.
As a visitor, I want not to be spammed with WhatsApp buttons, so that the experience remains uncluttered.

Page 13 of 39

3.16 Public Pages (Base Set)

As a visitor, I want the public site to contain Home, so that I have an entry point.
As a visitor, I want the public site to contain Services, so that I can browse offerings.
As a visitor, I want the public site to contain Service Details, so that I can read about a service.
As a visitor, I want the public site to contain About MASAR, so that I can learn about the center.
As a visitor, I want the public site to contain Doctor Profile, so that I can learn about the doctor.
As a visitor, I want the public site to contain Find Your Path, so that I can be guided.
As a visitor, I want the public site to contain FAQ, so that I can read common questions.
As a visitor, I want the public site to contain Contact, so that I can reach the clinic.
As a visitor, I want the public site to contain Privacy / Legal pages where required, so that legal content is available.
As a visitor, I want shared components including Header, Footer, Language switcher, WhatsApp CTA, and Responsive navigation, so that the experience is consistent.

3.17 Social Media (Public Behavior)

As a visitor, I want Instagram icons where appropriate (header where appropriate, footer, contact section), so that I can reach the official channel.
As a visitor, I want Facebook icons where appropriate, so that I can reach the official channel.
As a visitor, I want TikTok icons where appropriate, so that I can reach the official channel.
As a visitor, I want each visible social icon to redirect directly to the official MASAR social-media URL configured by the Admin, so that links are correct.
As a visitor, I want a social platform icon to appear only when the platform is configured AND enabled AND its URL passes server-side validation, so that broken or unsafe links are never shown.
As a visitor, I want disabled or unconfigured platforms to not appear, so that I only see valid links.
As a visitor, I want external links opening in a new tab to use target="_blank" rel="noopener noreferrer", so that browsing is safe.
As a system owner, I want the frontend to consume social links from CMS/API data with no hardcoded Instagram, Facebook, or TikTok URLs, so that social links are updatable without a frontend deployment.
As a system owner, I want the architecture to allow additional platforms later without changing the public UI architecture, so that MASAR can grow.

Page 14 of 39

3.18 Clinic Media & Logo (Public Behavior)

As a visitor, I want the website to use CMS-managed media as the source of truth for clinic-specific media (logo, doctor photo, clinic photos, service images, gallery images, equipment photos, nutrition images, treatment-room photos, reception photos, activity photos, and other approved clinic media), so that visuals stay current.
As a visitor, I want the MASAR logo loaded through the CMS/media source, so that the clinic's actual logo is shown without hardcoding a path (e.g., /images/masar-logo.png) as the permanent source of truth.
As a visitor, I want a fallback application-level placeholder if an asset is missing or broken, so that the UI does not break.
As a visitor, I want approved media such as the doctor profile image available with alt_ar and alt_en, so that images are accessible in both languages.
As a system owner, I want the same approved image reusable across the Doctor Profile page, Homepage Doctor section, and approved service/content sections, with the frontend referencing the media entity rather than duplicating file paths, so that media is managed centrally.

3.19 Administration System — Access & Structure

As an administrator, I want a secure Administration Dashboard as a core V1 feature, so that I can manage content without touching the database directly.
As a visitor, I want no public account requirement (no login/signup) in V1, so that I face no unnecessary friction.
As an administrator, I want an admin structure conceptually including /admin → Login → Dashboard → Content (Homepage, Services, Doctor Profile, FAQs, Testimonials, Pages) → Media → Settings (Contact, WhatsApp, Phone, Working Hours, Social Links, SEO, General) → Navigation → Analytics → Audit Logs, so that all administrative areas are organized.
As an administrator, I want an Admin media tree including Media (Logo, Doctor Photo, Clinic Images, Service Images, Gallery) and Settings (Contact, WhatsApp, Phone, Working Hours, Social Media → Instagram/Facebook/TikTok, SEO, General), so that I can navigate all media and settings areas.

Page 15 of 39

3.20 Admin CMS Responsibilities

As an administrator, I want to add new content records (services, FAQs, testimonials, pages, media), so that I can extend the site with new content.
As an administrator, I want to edit existing content records, so that I can correct and update content.
As an administrator, I want to manage the Homepage, so that homepage content is editable.
As an administrator, I want to manage the Hero, so that hero copy is editable.
As an administrator, I want to manage Services and Service details, so that service content is editable.
As an administrator, I want to manage the Doctor profile, so that doctor information is editable.
As an administrator, I want to manage FAQs, so that questions and answers are editable.
As an administrator, I want to manage Testimonials (where enabled), so that testimonials are manageable.
As an administrator, I want to manage the Gallery, so that gallery content is manageable.
As an administrator, I want to manage Contact information, Working hours, and Social links, so that clinic contact data is editable.
As an administrator, I want to manage WhatsApp settings, so that WhatsApp conversion is configurable.
As an administrator, I want to manage SEO metadata, so that search engine settings are editable.
As an administrator, I want to manage Navigation labels, so that navigation is editable.
As an administrator, I want to manage Arabic content and English content, so that both languages are independently editable.
As an administrator, I want to manage Media, so that all approved clinic media is managed centrally.

3.21 Draft / Preview / Publish

As an administrator, I want content to follow a Draft → Preview → Publish workflow, so that I can review before making content public.
As a system owner, I want draft content never to appear in public APIs, so that unreviewed content is never exposed.
As an administrator, I want publishing to be an explicit authorized action, so that only authorized users publish (e.g., POST /api/admin/services/{id}/publish and POST /api/admin/services/{id}/unpublish).
As a system owner, I want incomplete content not to be publishable, so that published pages are always complete.

Page 16 of 39

3.22 Admin Dashboard

As an administrator, I want a dashboard that is useful rather than overloaded, so that I can quickly assess content status.
As an administrator, I want dashboard cards including Published Services, so that I see key counts.
As an administrator, I want dashboard cards including Drafts, so that I see unfinished work.
As an administrator, I want dashboard cards including FAQs, so that I see FAQ counts.
As an administrator, I want dashboard cards including Gallery Images, so that I see media counts.
As an administrator, I want a Recent activity feed including Service Updated, so that I can see recent changes.
As an administrator, I want a Recent activity feed including FAQ Published, so that I can see recent changes.
As an administrator, I want a Recent activity feed including Doctor Profile Updated, so that I can see recent changes.
As an administrator, I want a Recent activity feed including Media Uploaded, so that I can see recent changes.
As an administrator, I want Quick actions including Add Service, so that I can act quickly.
As an administrator, I want Quick actions including Add FAQ, so that I can act quickly.
As an administrator, I want Quick actions including Upload Media, so that I can act quickly.
As an administrator, I want Quick actions including Edit Homepage, so that I can act quickly.
As an administrator, I want later analytics to include WhatsApp clicks, Phone clicks, Popular services, Find Your Path starts, and Find Your Path completions, so that I can understand engagement.

3.23 Admin Roles & Permissions

As a system owner, I want the architecture to support User → Role → Permissions, so that authorization is extensible.
As a system owner, I want potential future roles including Super Admin, Content Manager, and Editor, so that role structure can grow.
As a system owner, I want V1 to possibly begin with a single administrative role, but the architecture must not depend on isAdmin = true as the only authorization strategy, so that the permission model remains extensible.

Page 17 of 39

3.24 Admin Security

As a system owner, I want admin authentication to include secure password hashing, so that credentials are protected.
As a system owner, I want protected routes and authorization enforced server-side, so that admin areas are not exposed by hiding frontend pages.
As a system owner, I want server-side validation on admin operations, so that inputs are trusted only when validated.
As a system owner, I want login rate limiting, so that brute-force attempts are mitigated.
As a system owner, I want secure logout, so that sessions terminate safely.
As a system owner, I want secure cookies/tokens, so that sessions are protected.
As a system owner, I want CSRF protection where applicable, so that state-changing requests are protected.
As a system owner, I want secure headers, so that common web vulnerabilities are mitigated.
As a system owner, I want no plaintext passwords and no secrets in source control, so that credentials are never exposed.
As a system owner, I want admin APIs to verify authorization server-side, so that admin functionality cannot be accessed by bypassing the frontend.

3.25 Audit Logs

As a system owner, I want the action SERVICE_CREATED logged, so that creation is traceable.
As a system owner, I want the action SERVICE_UPDATED logged, so that edits are traceable.
As a system owner, I want the action SERVICE_PUBLISHED logged, so that publishing is traceable.
As a system owner, I want the action SERVICE_UNPUBLISHED logged, so that unpublishing is traceable.
As a system owner, I want the action MEDIA_UPLOADED logged, so that uploads are traceable.
As a system owner, I want the action MEDIA_DELETED logged, so that deletions are traceable.
As a system owner, I want the action FAQ_UPDATED logged, so that FAQ changes are traceable.
As a system owner, I want the action SETTINGS_UPDATED logged, so that settings changes are traceable.
As a system owner, I want audit log data to include user, action, entity, entity_id, timestamp, and metadata, so that logs are useful.
As a system owner, I want audit logs to not store unnecessary sensitive information, so that privacy is preserved.

Page 18 of 39

3.26 Revisions

As an administrator, I want basic revision/version history in V1, so that I can track prior versions of content.
As a system owner, I want full visual diff to be postponed, so that V1 scope stays focused.

3.27 Media Management (Admin)

As an administrator, I want the media capability Upload, so that I can add media.
As an administrator, I want the media capability Preview, so that I can verify media before publishing.
As an administrator, I want the media capability Replace, so that I can update media without breaking references.
As an administrator, I want the media capability Delete, so that I can remove media.
As an administrator, I want the media capability Reorder, so that I can control ordering.
As an administrator, I want the media capability Hide/show, so that I can toggle visibility.
As an administrator, I want to add Arabic alt text, so that media is accessible in Arabic.
As an administrator, I want to add English alt text, so that media is accessible in English.
As an administrator, I want to add Metadata, so that media is organized.
As a system owner, I want uploads validated server-side for file type, so that unsafe file types are rejected.
As a system owner, I want uploads validated server-side for MIME type, so that mismatched or spoofed content is rejected.
As a system owner, I want uploads validated server-side for file extension, so that disguised uploads are rejected.
As a system owner, I want uploads validated server-side for file size, so that oversized uploads are rejected.
As a system owner, I want uploads validated server-side for image dimensions where appropriate, so that invalid images are rejected.
As a system owner, I want safe filenames used for uploads, so that storage is safe.
As a system owner, I want no executable uploads allowed, so that the site cannot be compromised.
As a system owner, I want uploaded HTML or JavaScript never served as executable application content, so that stored content is not a script-execution vector.
As a system owner, I want SVG uploads restricted or sanitized because SVG can contain active content, so that stored media cannot execute scripts.
As a system owner, I want safe raster formats such as optimized WebP/AVIF/JPEG/PNG preferred, so that images are safe and performant.
As a system owner, I want images optimized and delivered responsively where practical, so that performance is preserved.

Page 19 of 39

3.28 Media Storage Architecture & Entity

As a system owner, I want a real Infrastructure boundary MediaStorage (Presentation → Application → MediaStorage interface → Infrastructure implementation → Object Storage/CDN), so that the application does not depend on the Render local persistent filesystem.
As a system owner, I want the domain/application layer to not depend directly on a provider SDK, so that the app remains portable and media is not lost on rebuild/redeploy.
As a system owner, I want a conceptual Media record containing id, storage_key, public_url_or_reference, media_type, mime_type, file_size, width, height, alt_ar, alt_en, category, is_visible, created_by, created_at, updated_at, so that media ownership and storage concerns are separated from page/service business logic.
As a system owner, I want services, pages, doctor profiles, and gallery entries to reference managed media rather than duplicating raw file info, so that media can be replaced centrally.
As an administrator, I want safe delete/unlink handling for media, so that I do not delete an asset that is still required by published content.
As a system owner, I want Admin warned before destructive actions, so that accidental loss is prevented.
As a system owner, I want published-content integrity preserved on media deletion, so that published pages do not silently break.

3.29 Admin Social Media Management

As an administrator, I want to add a social-media URL, so that a platform can be configured.
As an administrator, I want to edit a social-media URL, so that a link can be corrected.
As an administrator, I want to enable a platform, so that its icon appears publicly.
As an administrator, I want to disable a platform, so that its icon is hidden.
As an administrator, I want to preview the configured URL, so that I can verify it.
As an administrator, I want to change the display order, so that I can control ordering.
As an administrator, I want to update a URL without a frontend deployment, so that changes take effect immediately.
As a system owner, I want a conceptual SocialLink model: id, platform, url, enabled, display_order, created_at, updated_at, so that social links are stored consistently.
As a system owner, I want platform values instagram, facebook, and tiktok, so that V1 platforms are represented.
As a system owner, I want an extensible platform model rather than separate frontend logic per platform, so that new platforms can be added later.
As a system owner, I want social URLs validated for HTTPS, so that secure links are preferred.
As a system owner, I want javascript: URLs rejected, so that script-execution vectors are blocked.
As a system owner, I want data: URLs rejected, so that unsafe protocols are blocked.
As a system owner, I want unsafe protocols rejected, so that malformed or dangerous URLs are blocked.
As a system owner, I want malformed URLs rejected, so that only valid links are configured.
As a system owner, I want only valid absolute external URLs accepted, so that Admin-provided URLs are not a script-execution vector.

Page 20 of 39

3.30 Admin Logo & Image Management

As an administrator, I want to upload the MASAR logo, so that branding is managed.
As an administrator, I want to replace the MASAR logo, so that branding can be updated.
As an administrator, I want to preview the MASAR logo, so that I can verify the asset.
As an administrator, I want to remove/disable the logo where appropriate, so that I can control branding.
As an administrator, I want to maintain relevant logo metadata when applicable, so that the asset is documented.
As an administrator, I want to upload and replace the doctor's profile photo with metadata image, alt_ar, alt_en, so that the doctor image is accessible and reusable.
As an administrator, I want to classify images using the category Clinic, so that media is organized.
As an administrator, I want to classify images using the category Reception, so that media is organized.
As an administrator, I want to classify images using the category Treatment Rooms, so that media is organized.
As an administrator, I want to classify images using the category Equipment, so that media is organized.
As an administrator, I want to classify images using the category Doctor, so that media is organized.
As an administrator, I want to classify images using the category Nutrition, so that media is organized.
As an administrator, I want to classify images using the category Activities, so that media is organized.
As an administrator, I want to classify images using the category Other, so that media is organized.
As an administrator, I want to associate media with services/pages where needed, so that images appear in the right context.
As an administrator, I want the Admin UI to make the purpose of alt text clear to non-technical staff, so that accessibility metadata is used correctly.
As a system owner, I want decorative images explicitly treated as decorative rather than given meaningless alt text, so that accessibility is correct.

3.31 CMS Source-of-Truth Rule

As a system owner, I want clinic-specific content and media editable without a frontend deployment, including logo, doctor image, clinic images, service images, gallery images, social URLs, contact details, working hours, WhatsApp settings, phone number, and approved text content, so that staff can manage the site.
As a system owner, I want the frontend to consume published CMS data through stable API/application contracts, so that public behavior remains stable.

Page 21 of 39

3.32 AI Assistant (Optional, V1.5)

As a visitor, I want an optional assistant named MASAR Assistant, positioned not as an "AI Doctor", so that it is clearly a secondary helper.
As a visitor, I want the assistant to explain services, so that it helps without overstepping.
As a visitor, I want the assistant to answer approved FAQs, so that it helps without overstepping.
As a visitor, I want the assistant to help me navigate the website, so that it helps without overstepping.
As a visitor, I want the assistant to help me choose where to start, so that it helps without overstepping.
As a visitor, I want the assistant to provide contact information, so that it helps without overstepping.
As a visitor, I want the assistant to route me to WhatsApp, so that it helps without overstepping.
As a visitor, I want the assistant to not diagnose, so that medical safety is preserved.
As a visitor, I want the assistant to not prescribe, so that medical safety is preserved.
As a visitor, I want the assistant to not make clinical decisions, so that medical safety is preserved.
As a visitor, I want the assistant to not replace professionals, so that medical safety is preserved.
As a visitor, I want the assistant to not promise outcomes, so that medical safety is preserved.
As a system owner, I want the website to remain fully useful if the assistant is disabled, so that the core experience is independent.
As a system owner, I want an AssistantProvider abstraction with the flow Assistant UI → Assistant Application Service → Approved MASAR Content → AssistantProvider → AI Provider, so that AI vendors are replaceable.
As a system owner, I want the AI provider to never directly access the production database and only approved clinic content exposed to the assistant, so that data is protected.
As a system owner, I want provider-specific implementation to live in Infrastructure, so that boundaries are clean.

Page 22 of 39

3.33 Analytics

As a system owner, I want an AnalyticsProvider abstraction, so that analytics vendors are replaceable.
As a system owner, I want the event service_viewed, so that I can measure engagement.
As a system owner, I want the event find_path_started, so that I can measure engagement.
As a system owner, I want the event find_path_completed, so that I can measure engagement.
As a system owner, I want the event whatsapp_clicked, so that I can measure conversion.
As a system owner, I want the event phone_clicked, so that I can measure conversion.
As a system owner, I want the event map_clicked, so that I can measure engagement.
As a system owner, I want the event faq_opened, so that I can measure engagement.
As a system owner, I want the event language_changed, so that I can measure engagement.
As a system owner, I want the event assistant_opened, so that I can measure engagement.
As a system owner, I want the event social_link_click, so that I can measure social interactions.
As a system owner, I want no unnecessary medical or sensitive personal information collected, so that analytics is privacy-conscious.
As an administrator, I want to later view WhatsApp clicks, Phone clicks, Popular services, Find Your Path usage, and Social-link interactions, so that I can make decisions.

Page 23 of 39

3.34 API Architecture

As a system owner, I want the public endpoint GET /api/services, so that published services are served.
As a system owner, I want the public endpoint GET /api/services/{slug}, so that a published service is served.
As a system owner, I want the public endpoint GET /api/faqs, so that published FAQs are served.
As a system owner, I want the public endpoint GET /api/site-settings, so that published site settings are served.
As a system owner, I want the public endpoint GET /api/doctor-profile, so that the published doctor profile is served.
As a system owner, I want the public endpoint GET /api/social-links, so that published social links are served.
As a system owner, I want the admin endpoints POST/PATCH/DELETE /api/admin/services, so that services can be managed.
As a system owner, I want the admin endpoints POST /api/admin/services/{id}/publish and POST /api/admin/services/{id}/unpublish, so that publish/unpublish are explicit actions.
As a system owner, I want the admin endpoints POST/PATCH /api/admin/faqs, so that FAQs can be managed.
As a system owner, I want the admin endpoints POST /api/admin/media, PATCH /api/admin/media/{id}, and DELETE /api/admin/media/{id}, so that media can be managed.
As a system owner, I want the admin endpoint PATCH /api/admin/social-links/{id}, so that social links can be managed.
As a system owner, I want public APIs to expose approved published content rather than raw database structures, so that internal schema is not leaked.

3.35 Application Use Cases & Domain Concepts

As a system owner, I want the application use cases CreateService, UpdateService, PublishService, UnpublishService, ManageFAQ, ManageMedia, UpdateDoctorProfile, UpdateContactSettings, ManageHomepage, BuildWhatsAppMessage, and TrackAnalyticsEvent, so that application services coordinate business operations.
As a system owner, I want domain concepts including Service, DoctorProfile, FAQ, Testimonial, Media, Page, SiteSetting, and NavigationItem, independent from framework-specific implementation, so that the domain is clean.
As a system owner, I want the Presentation layer responsible for Controllers, Requests, API Resources, DTO mapping, HTTP concerns, and Authentication endpoints, with controllers free of business logic.
As a system owner, I want the Infrastructure layer responsible for Database, Storage, External APIs, Analytics, AI Provider, WhatsApp integration, and Email if added later.

3.36 Frontend Composition

As a system owner, I want the frontend structured into app, components (ui/layout/navigation/sections), features (services, find-your-path, faq, contact, testimonials, assistant), pages, hooks, lib, services, i18n, types, styles, and utils, so that feature-specific logic stays inside its feature.
As a system owner, I want sections composed as Hero, ServiceGrid, PathFinder, TreatmentProcess, DoctorSection, Testimonials, FAQPreview, ContactCTA instead of a monolithic "MegaHomePage", so that components are maintainable.
As a system owner, I want no giant components that combine API calls, business logic, translation, analytics, and every page section, so that components stay cohesive.

Page 24 of 39

3.37 Feature Priority

As a system owner, I want V1 Required: Arabic/English, RTL/LTR, responsive premium design, Home, Services, Service Details, About, Doctor Profile, Find Your Path, FAQ, Contact, WhatsApp, Admin authentication, Admin dashboard, CMS, Draft/Preview/Publish, Media management, SEO basics, Accessibility, Audit logs, Secure architecture, and Production deployment.
As a system owner, I want V1.5: Interactive body map, Testimonials, Clinic gallery, Lightweight analytics, MASAR Assistant, and Revision history.
As a system owner, I want V2: Patient accounts, Appointments, Patient portal, Treatment plans, Progress tracking, Nutrition plans, Notifications, and Payments if required.

3.38 Product-Integrity & Anti-Pattern Rules (Explicitly "Not")

As a system owner, I want the product to NOT create giant files, so that maintainability is preserved.
As a system owner, I want the product to NOT duplicate logic, so that behavior stays consistent.
As a system owner, I want the product to NOT hardcode CMS content, so that content remains editable.
As a system owner, I want the product to NOT put database logic inside the UI, so that boundaries are clean.
As a system owner, I want the product to NOT put business logic inside controllers, so that responsibilities are separated.
As a system owner, I want the product to NOT create unnecessary abstractions, so that complexity is controlled.
As a system owner, I want the product to NOT add libraries without a reason, so that the codebase stays lean.
As a system owner, I want the product to NOT build features only to demonstrate technology, so that effort targets real needs.
As a system owner, I want the product to NOT implement booking without a real requirement, so that V1 scope stays focused.
As a system owner, I want the product to NOT invent medical claims, credentials, testimonials, or statistics, so that trust is preserved.
As a system owner, I want the product to NOT use AI merely as a marketing gimmick, so that AI is added only when it delivers real user value.
As a system owner, I want the product to NOT sacrifice UX for architecture, so that the experience remains simple.
As a system owner, I want the product to NOT sacrifice architecture for a quick demo, so that the platform remains extensible.
As a system owner, I want the product to NOT commit secrets, so that credentials are never exposed.
As a system owner, I want the product to NOT store uploaded production media only on ephemeral application storage, so that media is not lost on rebuild/redeploy.

4. User Personas

Page 25 of 39

4.1 Prospective Patient (Public Visitor)

A person exploring MASAR to understand the clinic, its services, and how to make contact. Persona variants share the same workflow and are grouped: someone experiencing pain, someone with a sports injury, someone needing rehabilitation, someone interested in therapeutic nutrition, someone wanting to improve movement, and someone unsure where to start. This persona can be first-time or returning.

Goals: Understand MASAR quickly, explore services, learn about the doctor and treatment philosophy, find the most relevant service, read trusted educational information, contact MASAR easily, and find the clinic location and working hours.
Visible information & actions: public pages, service list and details, Find Your Path guidance, doctor profile, FAQ, contact details, WhatsApp CTA, phone CTA, social links, language switcher.
Constraints: No public account required; no online booking in V1; Find Your Path is guidance only, not diagnosis.

4.2 Authorized Administrator

Authorized MASAR staff who manage website content without touching the database directly. The role architecture supports future Super Admin, Content Manager, and Editor roles, though V1 may begin with a single administrative role.

Goals: Manage and publish bilingual content and media, keep clinic content accurate, and reach WhatsApp/contact settings centrally.
Visible information & actions: Admin dashboard, content management, media management, settings, navigation, analytics, audit logs, Draft/Preview/Publish workflow.
Constraints: All actions authorized and validated server-side; publishing is an explicit authorized action; draft content never appears publicly.

4.3 System Actors (not personas)

Integration systems and external services that interact through abstractions: WhatsApp (primary conversion), Analytics Provider, AI Provider (AssistantProvider, optional), Media Storage / Object Storage / CDN, and Google Maps / Directions. Outbound-only recipients (e.g., the WhatsApp contact) are external recipients.

5. Core User Flows

Page 26 of 39

5.1 Prospective Patient — Discover, Understand, Contact

Lands on Home and immediately interprets "Move Better. Live Better." and supporting text.
Uses the header (with compacting on scroll) or the mobile menu to explore.
Uses "What Brings You Here?" to select a general goal (e.g., "I need rehabilitation").
Optionally uses Find Your Path to be guided to relevant services.
Explores a service and its detail page (What This Service Is → Who It May Be Relevant For → What The Process May Look Like → What To Expect → Related Services → FAQ).
Reaches a contextual WhatsApp CTA and sends a prefilled, service-aware message (secondary path: phone call).
Optionally reviews FAQ, Doctor Profile, About, and social links.

5.2 Prospective Patient — Find Your Path

Starts the guided flow ("What are you looking for?").
Selects the issue or goal ("Where is the issue or goal?" — Neck, Shoulder, Back, Hip, Knee, Ankle, Other).
Selects what best describes the situation.
Receives relevant MASAR service suggestions.
Reads the statement that the tool is for general guidance and service discovery only and does not provide a medical diagnosis.
Continues to a service page or WhatsApp.

5.3 First-Time Visitor — Before Your First Visit

Opens "Before Your First Visit".
Learns what to expect, what to bring, how the first interaction works, how to contact MASAR, the location, and working hours.
Contacts MASAR via WhatsApp or phone, or uses Directions.

Page 27 of 39

5.4 Administrator — Edit and Publish Content

Authenticates to /admin.
Views the dashboard (Published Services, Drafts, FAQs, Gallery Images; Recent activity; Quick actions).
Adds or edits Arabic and/or English content (Save as Draft).
Previews the content.
Publishes (explicit authorized action) or Unpublishes.
Action is recorded in audit logs.

5.5 Administrator — Manage Media

Opens the Media area (Logo, Doctor Photo, Clinic Images, Service Images, Gallery).
Uploads an image (server-side validated for file type, MIME type, extension, size, dimensions, filename safety).
Adds Arabic/English alt text and metadata; assigns a category.
Replaces, reorders, hides/shows, or previews media.
Deletes safely (warned before destructive actions; published-content references preserved).

5.6 Administrator — Manage Social Links

Opens Settings → Social Media.
Adds or edits an Instagram, Facebook, or TikTok URL.
Enables/disables each platform and sets display order.
Previews the configured URL; server-side validation rejects malformed and unsafe URLs.
Saves — the public frontend reflects changes with no frontend deployment.

6. Visuals, Colors, and Theme

Page 28 of 39

6.1 Brand Personality

MASAR should feel calm, clean, professional, human, modern, trustworthy, premium, comfortable, and clinical but warm — a quiet, confident digital space for movement, recovery, and care.

6.2 Color Direction (inspired by the MASAR logo)

Primary: Deep Teal
Secondary: Natural Green
Accent/soft: Soft Sage
Background: Warm White / Off-white
Primary text: Charcoal
Secondary text: Muted Gray

Page 29 of 39

6.2.1 Applied Creative Direction — Humane Technology for Recovery

The project-wide creative direction is humane technology for recovery — warm, breath-paced care (muse: Yves Béhar). MASAR is a health-care service where visitors arrive anxious, in pain, or unsure where to start; the register is calm reassurance and human warmth, never clinical coldness and never aggressive marketing. Arabic must feel first-class, so the type system must carry a warm humanist voice in both scripts.

Palette (light mode): background #F7F3EC, surface #FFFFFF, text #2A2723, primary #4F6B5D, accent #C96A4B, muted #8A8178. Warm oat-white ground with pure white cards; sage-green primary carries trust and health without clinical blue; terracotta accent is reserved for CTAs, the WhatsApp action, and active states only; ink-brown text keeps contrast high; muted warm grey for metadata and captions. Colour proportion: 70% oat ground, 20% white surfaces, 8% sage, 2% terracotta.

Typography: headings Fraunces — warm humanist sans headings in medium weight with slightly open tracking (0.01em) and generous line-height (1.15); headings never all-caps, never tight-tracked; Arabic headings use Noto Kufi Arabic at medium weight with matching optical size. Body copy in Karla regular with 1.7 line-height for calm reading; Arabic body uses Noto Naskh Arabic. Labels and micro-copy in Karla medium; small caps avoided in Arabic. Scale: 1.25 modular scale — display 56px mobile / 84px tablet / 112px desktop (clamp(3.5rem, 7vw, 7rem)); h1 40/56/72; h2 28/40/48; h3 22/26/30; body 17/18/18; caption 14/14/15.

Shape language: soft continuous curves everywhere — 24px radii on cards, 999px pill buttons, 32px radii on image frames and the Find Your Path panel; organic rounded section dividers (a single gentle arc, not a wave); no sharp corners except hairline rules; soft offset shadows (0 8px 24px rgba(42,39,35,0.06)) rather than borders.

Layout: human-scale single-column rhythm with generous margins — 24px mobile / 48px tablet / 96px desktop gutters, max content width 1180px. Sections alternate between full-width warm-white bands and oat bands with large vertical breathing room (96–160px). The homepage runs hero → "What Brings You Here?" → Find Your Path → Treatment Philosophy → Doctor → Why MASAR → Before Your First Visit → FAQ preview → Contact CTA → footer. RTL is a first-class layout, not a mirror afterthought: the whole grid uses logical properties, the language switcher sits in the header start-side, and Arabic type metrics drive the same spacing scale.

Motion: breathing, slow easing (cubic-bezier(0.22, 0.61, 0.36, 1), 500–700ms) on section reveals and one purposeful hero entrance; hover states are soft colour and shadow shifts, never bounce; Find Your Path steps cross-fade with a gentle 300ms slide; all motion stops under prefers-reduced-motion, showing complete content. Motion tempo: restrained; hero dimensionality: layered_2d; hero drama: bold.

Imagery: softly lit photography of real hands-on therapy, natural light, warm textiles and treatment-room materials; no stock-model smiles, no before/after claims, no invented credentials. The doctor photo is a real clinic-approved portrait on a warm plain ground. Illustrative spot art is hand-drawn warm line work in sage and terracotta for the Treatment Philosophy journey.

Hero direction: a composed, warm two-part hero on the oat ground — on the start side (left in LTR, right in RTL) an oversized Fraunces/Kufi headline "Move Better. Live Better." set at clamp(3.5rem, 7vw, 7rem), stacked over a short CMS-editable paragraph, with two pill CTAs pinned beneath — solid sage "Explore Services" and outlined terracotta "Chat on WhatsApp". On the opposite side, a soft-cornered full-height photograph of a real treatment moment, cropped so the therapist's hands and the patient's shoulder fill the frame, bleeding off the bottom edge. A single gentle arc separates the two halves. No gradient blob, no centred text, no blue button.

Signature moves:

Oversized bilingual headline spanning the hero's start-side column at up to 112px desktop, with the Arabic version typeset at matching optical weight rather than shrunk as a translation.
A "What Brings You Here?" row of six pill choices in warm oat and white that behave like a gentle conversation opener — selecting one reveals a short human sentence and links into Find Your Path, never a diagnosis.
Find Your Path as a soft rounded panel with three calm steps and a visible progress indicator drawn as a growing sage arc, keyboard-navigable with logical RTL ordering.
Treatment Philosophy rendered as a five-stop hand-drawn warm line path (Assessment → Understanding Your Needs → Personalized Care → Progress → Better Movement) with no outcome promises.
A scroll-compacting header that shifts from transparent oat to white with a hairline warm border, keeping the language switcher and WhatsApp pill always reachable.

Avoid: clinical blue or indigo primaries and any blue-on-white SaaS look; gradient blob heroes, glassmorphism cards, and grids of identical hover-lift cards; Inter, Roboto, Poppins, system-ui, or any neutral default font for headings or body; invented certifications, awards, statistics, testimonials, or "best clinic" claims; before/after imagery or any visual promise of specific outcomes; sharp-cornered, dense dashboard styling on public pages; treating Arabic as a mirrored afterthought rather than a first-class typographic system; bouncy or playful motion that undercuts a health-care register. The generic indigo/blue-on-white SaaS template is forbidden for this project.

Readable text and controls stay whole at every viewport: headlines, wordmarks, labels, numbers, cards' text and controls stay entirely inside the viewport and their container at 375px, 768px and 1280px, wrapping or scaling (for example font-size: clamp(...) with its mobile size) to fit, and no other element covers any part of them. Imagery, decoration and motion follow the creative direction: a photograph, artwork, shape, texture or animation may be cropped, bled off an edge, rotated, overlapped or cut exactly as the direction asks, as long as it covers no readable text or control. Moving and scrollable content (marquees, tickers, carousels, horizontally scrollable rows) may cross the viewport or container edge by design: judge it by whether it actually moves or scrolls and whether every item becomes fully readable as it passes, never by the item cut at the edge in a still frame. With prefers-reduced-motion it stops and shows whole items: they wrap into rows, or sit in a horizontally scrollable row (overflow-x: auto) whose further items are reached by scrolling. Where a direction, requirement, brief or finding asks readable text or a control to be cropped, clipped, covered or run off an edge, keep it whole and carry the gesture with imagery or decoration instead; for readable text and controls this rule takes precedence.

Page 30 of 39

6.2.2 Landing Hero Motion Brief

At the direction's restrained motion tempo, the landing hero is a product-specific 2D DOM/SVG/CSS composition implemented with Motion for React (motion/react) or GSAP — one contained loop, no scroll-jacking.

Input → transformation → outcome thesis: the visitor's arrival (input) is met by a single breath-paced entrance that settles the headline, paragraph and CTAs into place and then holds a slow, contained loop (transformation), producing the outcome of a calm, trustworthy first impression that never competes with the content.
Focal subject: the oversized bilingual headline "Move Better. Live Better." on the start-side column, with the two pill CTAs beneath it.
Visible layers: (1) oat ground band; (2) the single gentle arc divider drawn as an SVG path; (3) the start-side text column (headline, paragraph, CTAs); (4) the soft-cornered treatment photograph on the opposite side, bleeding off the bottom edge; (5) the scroll-compacting header above all layers.
Loop: one staged opening — arc path draws in, headline and paragraph rise and fade in, CTAs settle last — followed by a very slow, low-amplitude breathing drift on the arc and photograph (no bounce, no repeat-on-scroll).
Composed first frame: the arc already partially drawn, the headline fully legible at its mobile clamp size, both CTAs visible and unclipped, and the photograph cropped so hands and shoulder fill the frame.
Optional interaction: hovering or focusing a CTA shifts colour and shadow softly; the header compacts on scroll with a smooth transition and subtle border/shadow.
Responsive behavior: at 375px the hero stacks to a single column with the headline at its mobile clamp size, CTAs full-width and reachable, and the photograph below the text; at 768px and 1280px the two-part composition returns with the arc divider.
Reduced-motion fallback: under prefers-reduced-motion all entrance and loop motion stops and the complete composed first frame is shown statically, with every headline, label and control whole and readable.

6.2.3 Landing Hero 3D Scene Brief — DIRECTION-DERIVED

The creative direction's hero dimensionality is layered_2d, so no Canvas/R3F/Drei scene is required for the landing hero. If a spatial treatment is later introduced, it must remain a layered 2D composition (DOM/SVG/CSS) rather than a WebGL scene, and it must not introduce robot imagery, futuristic AI visuals, glowing blobs, or excessive 3D.

Page 31 of 39

6.3 Semantic Design Tokens (centered, non-scattered)

The system uses centralized semantic tokens and must not scatter raw color values throughout the application.

primary
primary-hover
secondary
background
surface
surface-muted
text
text-muted
border
success
warning
error

6.4 Visual Rules — Use

Realistic/natural clinic imagery; natural healthcare imagery; strong negative space; comfortable typography; soft surfaces; subtle borders; restrained shadows; organic shapes; editorial layouts; calm composition; subtle motion; natural transitions.

6.5 Visual Rules — Avoid

Neon gradients; futuristic AI visuals; robot imagery; excessive glassmorphism; excessive 3D; glowing blobs; dark SaaS aesthetics; huge floating UI elements; excessive rounded cards; excessive parallax; scroll-jacking; bounce-heavy animations; animation on every element; generic AI-generated-looking layouts; generic medical templates; stock-photo overload.

Page 32 of 39

6.6 Typography

Arabic and English are first-class citizens. The application must properly support Arabic typography, English typography, RTL, LTR, and mixed Arabic/English content, with attention to font selection, font loading, line height, letter spacing, responsive sizing, text wrapping, mixed-direction punctuation, numbers, dates, phone numbers, and URLs. Arabic must not be treated as a translated version of the English UI.

7. Signature Design Concept

A quiet, confident digital space for movement, recovery and care.

The visual language should feel intentionally designed for MASAR, not like an AI demo, SaaS dashboard, generic medical template, or portfolio website. The visitor should notice calm, clarity, trust, quality, and ease — not "look how much technology we used." The final creative direction resolves as:

Calm → Clear → Human → Professional → Trustworthy

The website should feel like a natural, premium digital extension of a physical therapy and therapeutic nutrition center, with strong engineering underneath and an intentionally simple experience on top.

8. Interaction Model & Motion Direction

Page 33 of 39

8.1 Interaction Model

Principle: Guide the user, don't overwhelm the user. At every point the visitor should understand: (1) Where am I? (2) What can I do here? (3) What should I do next?
The website should minimize unnecessary friction and keep the public UI simple while the Admin UI stays friendly.
Conversion is intentionally low-friction: WhatsApp (primary), Phone (secondary).

8.2 Motion Philosophy

Animation should communicate movement, continuity, progress, and calmness. Animations must be smooth, lightweight, purposeful, and fast enough not to slow the experience. The system must respect prefers-reduced-motion.

8.3 Motion Boundaries

Never sacrifice performance, accessibility, or usability for animation. Avoid scroll-jacking, bounce-heavy animations, animation on every element, and excessive parallax. Header transitions (compact/smooth/subtle) are permitted.

9. Non-Functional Requirements

9.1 Security

The entire application follows secure-by-default principles: HTTPS, secure authentication, authorization, input validation, output sanitization, rate limiting, CSRF protection where applicable, secure headers, secure cookies/tokens, upload validation, no executable uploads, environment variables for secrets, no credentials in Git, restricted admin APIs, and safe error handling.
Never expose to the frontend: database credentials, admin passwords, AI API keys, storage credentials, or private tokens.
CORS: configure explicitly; production allows only trusted frontend origins; never use Access-Control-Allow-Origin: * for authenticated/admin APIs; the production frontend origin must be configurable.
Health check: GET /api/health returns a safe response (e.g., {"status": "ok"}) and must not expose credentials, internal infrastructure, secrets, or stack traces.
Environment configuration: maintain separate Development, Staging, and Production configurations; never commit .env, .env.local, .env.production, or any secret files.

Page 34 of 39

9.2 Medical Safety

The website must not diagnose users, prescribe treatment, provide individualized medical decisions, guarantee treatment outcomes, or invent medical claims, credentials, statistics, or testimonials. Find Your Path is a service discovery tool, not a diagnosis engine. The AI Assistant is a navigation/information assistant, not a medical professional. For urgent situations, users should be directed toward appropriate professional or emergency care rather than being diagnosed by the website.

9.3 Privacy by Design

Do not collect patient medical information simply because the system technically could. V1 should avoid storing diagnoses, treatment records, detailed identifiable symptoms, and unnecessary personal information. A future Patient Portal will require a separate privacy and security design before implementation.

9.4 Performance

Prioritize responsive images, modern image formats, lazy loading, font optimization, code splitting where useful, minimal unnecessary JavaScript, caching, stable layout, and lightweight animations. Avoid unnecessary client-side rendering. Do not sacrifice performance for visual effects.

9.5 Accessibility

Implement semantic HTML, keyboard navigation, visible focus states, accessible buttons, accessible forms, alt text, proper heading hierarchy, sufficient color contrast, screen-reader labels, and reduced-motion support. Use ARIA only when necessary.

Page 35 of 39

9.6 SEO

Implement page title, meta description, canonical URLs, Open Graph metadata, sitemap, robots configuration, semantic headings, clean URLs, Arabic/English metadata, correct localized alternate URLs, and appropriate structured data. Avoid keyword stuffing.

9.7 Observability

Implement structured logging, meaningful error handling, request IDs/correlation IDs where useful, frontend error boundaries, admin audit logs, and monitoring hooks. Never expose stack traces or internal errors to public users.

9.8 Testing

Backend: unit logic, API/feature flows, authentication, authorization, validation, publishing workflow.
Frontend: critical components, Find Your Path, forms, RTL, LTR, language switching.
E2E: public navigation, service discovery, service details, WhatsApp flow, admin login, admin editing, Draft, Preview, Publish, language switching.

9.9 Caching

Potentially cache published services, FAQs, doctor profile, site settings, and navigation. Invalidate relevant cache when content is updated, published, or unpublished. Do not over-engineer caching in V1.

9.10 Database Requirements

Use primary keys, foreign keys, unique constraints, appropriate indexes, timestamps, transactions, and an appropriate soft-delete strategy. Data integrity rules: localized slugs must be unique where required; foreign keys must remain valid; required content must exist before publishing; draft content must never appear publicly; only authorized administrators can publish; media deletion must not silently break published pages.

Page 36 of 39

9.11 Quality Bar

Design: should feel like a premium physical therapy and therapeutic nutrition center — not an AI demo, SaaS dashboard, generic medical template, or portfolio site.
UX: a first-time visitor should understand MASAR quickly, find services easily, understand what to do next, and reach WhatsApp easily, with a felt sense of ease.
Mobile: excellent mobile experience; polished Arabic mobile UX; reachable buttons; natural navigation.
Architecture: business logic outside controllers, clear responsibilities, appropriate dependency inversion, clear domain concepts, proper DB relationships; new features should not require rewriting unrelated modules.
Security: admin protected, uploads validated, secrets externalized, public APIs restricted appropriately.
Performance: optimized images, reasonable initial JS, lightweight animation, useful caching, no unnecessary rendering.

Page 37 of 39

9.12 Definition of Done

Public Website: complete; Arabic and English polished; RTL and LTR correct; mobile excellent; services, doctor profile, FAQs, media, and contact details CMS-driven; social links CMS-driven; WhatsApp works; Find Your Path works.

Administration: admin authentication works; authorization works; dashboard works; content management works; Draft, Preview, Publish, and Unpublish work; media upload, replacement, and secure management work; social URL management works; audit logs work.

Safety: no diagnosis, no fake medical claims, no fake credentials, no fake testimonials, no fake statistics.

SEO: metadata, sitemap, robots, canonicals, and localized SEO work.

Accessibility: keyboard navigation, focus states, contrast, image alt text, accessible forms, and reduced motion work.

Security: secrets not committed; admin APIs protected; inputs validated; uploads validated; external URLs validated; authentication secure; authorization enforced server-side; production media uses proper object storage/CDN.

Deployment: frontend deploys to Cloudflare Pages; backend deploys to Render; database runs on Neon; environment variables configured; CORS configured; HTTPS works; health endpoint works; production build works; logging verified; backup/recovery documented.

Testing: critical backend, frontend, admin, Find Your Path, WhatsApp, RTL/LTR, and mobile workflows tested.

10. Tech Stack

Page 38 of 39

10.1 Hosting & Deployment

Frontend → Cloudflare Pages
Backend → Render
Database → Neon PostgreSQL Use free or low-cost tiers where currently available and appropriate; verify current provider plans, limitations, and requirements before deployment and do not assume free-tier conditions are permanent.

10.2 Frontend — Cloudflare Pages

Responsibilities: host frontend, serve HTTPS, production builds, environment configuration, production domain, and CDN/caching where appropriate. The frontend must never contain private secrets; only public environment variables may be exposed (e.g., PUBLIC_API_URL=, PUBLIC_SITE_URL=). Never expose DATABASE_URL, AUTH_SECRET, COOKIE_SECRET, AI_API_KEY, STORAGE_SECRET, or ADMIN_PASSWORD.

10.3 Backend — Render

Responsibilities: host backend API, run application/business logic, authentication, authorization, admin APIs, database communication, media/storage integrations, analytics, AI integrations, logging, and health checks. The backend must be independent from the frontend runtime; public APIs and admin APIs must remain clearly separated; future Patient APIs should have their own authenticated boundary.

Page 39 of 39

10.4 Database — Neon PostgreSQL

Production relational database: Neon PostgreSQL. Requirements: secure connection, environment-based connection, database migrations, seed data where appropriate, foreign keys, unique constraints, indexes, transactions, and timestamps. Database credentials must be stored as Render environment variables/secrets and never committed to Git. Use a database driver/ORM configuration appropriate for Neon PostgreSQL.

Conceptual entities:

users, roles, permissions
services, service_translations, service_faqs, service_media, service_relations
doctor_profiles, doctor_profile_translations
faqs, faq_translations
testimonials, testimonial_translations
media, media_translations
pages, page_transl

No completed page designs yet.

Completed design pages will appear here when they are ready to preview.

No completed page designs yet.

Completed design pages will appear here when they are ready to preview.

file-job

Comments (0)