# AZVYRA — Complete Platform Documentation > Version **2.0** · Last updated **2026-11-06** > **AZVYRA** platform · Founded and led by **Captain Abdulaziz Al-Ghamdi** · Built by **BYTE ON** --- ## Contents ### Getting started - Scope & assumptions - Platform overview - The trainee journey - Roles & permissions - Website & landing page - Sign-up & sign-in - Intake questionnaire - Admin dashboard - Notification bell ### Trainee management - Registration requests - Trainee records - Plans & subscriptions - Payments & invoices ### Training & nutrition - Exercise library - Workout programs - Nutrition & calories - Measurements & progress - Daily habits - Check-ins & weekly review ### Trainee experience - Trainee dashboard - Mobile app ### Communication - Chat - Meetings (Google Meet) - Notifications & reminders - AI assistant ### Performance & reporting - Analytics & Google Sheets - Reports - Activity log - Page & video tracking ### Platform operations - Users & team - Settings - Content & website (CMS) - Security, privacy & compliance - Performance & quality ### Technical reference - Architecture - Data model - API - Integrations - Roadmap & phases - Open questions - Changelog ### Appendices - Additions to the brief - Binding operating rules --- # Getting started > Understand the platform, roles, the trainee journey and sign-up. ## Scope & assumptions > What v2 covers, what needs separate approval, and the operating assumptions behind the build. **Category:** Getting started · **Roles:** Admin · Head coach · Technical owner This document describes **a single-brand platform for one head coach** in the first release, with room to add assistant coaches and nutritionists. It is not assumed to be a multi-tenant SaaS product unless the client explicitly approves that direction. - **Web:** the public website, registration, and the admin, coach and trainee portals. - **Mobile:** native iOS and Android apps consuming the Laravel REST API; no separate databases are created for the apps. - **Source of truth:** the platform database is authoritative. Google Sheets is a presentation, export and sync channel, never an independent operating database. - **Business decisions:** pricing, plan contents, refund policy, session counts and renewal eligibility must be approved in writing by the client. - **Legal decisions:** privacy policy, tax, e-invoicing and app-store terms need review by a qualified specialist before launch. This documentation is not legal advice. - **Health data:** treated as sensitive data. Least privilege and data minimisation apply everywhere. ### In scope vs. requiring separate approval | Item | Status | |---|---| | Marketing site, landing page and CMS | In scope | | Trainee registration, questionnaire and admin review | In scope | | Plans, subscriptions and payments | In scope once a payment provider is selected | | Training programs, nutrition plans and coaching | In scope | | Chat, notifications, Google Meet and Google Sheets | In scope, subject to account and permission approval | | iOS and Android apps | Separate phase after the API and web experience are stable | | Supplement store or product sales | Out of current scope | | InBody devices, wearables and health integrations | Later phase, subject to API availability and client approval | | Multi-coach SaaS | Separate architecture and commercial decision | > **Note — Delivery reality** > > The phases in Roadmap & phases are estimates for a small team. They are re-baselined after design sign-off, provider selection and confirmation of the open questions. --- ## Platform overview > The platform at a glance: components, capabilities and who it serves — from intake to reporting. **Category:** Getting started · **Roles:** Admin · Head coach · Technical owner · Trainee AZVYRA is an end-to-end platform that moves a coach's work out of WhatsApp and scattered spreadsheets into one organised place: from the first enquiry, to the subscription, to the plan, to daily tracking, to reporting. **What the platform does** - Presents the coach and services on a professional landing page and captures new trainees. - Collects the trainee's profile, goals and health status through an intake questionnaire. - Lets the admin review the request, approve it, and assign a plan and programs. - Gives the trainee one dashboard for workouts, meals, calories, measurements and progress. - Adds chat, Google Meet sessions and automatic reminders. - Uses an AI assistant to read the numbers and suggest next steps. - Gives the admin complete visibility: KPIs, reports, an activity log and subscription alerts. **Components** | Component | Technology | Users | |---|---|---| | Website + web app | Laravel | Everyone | | Mobile app | Flutter (or React Native) | Trainee + coach | | API | Laravel REST | App + web | | Background jobs | Laravel Queue + Scheduler | System | > **Tip — The product in one sentence** > > A subscription-first coaching workspace where the trainee always knows what to do today, and the coach always knows who needs attention. --- ## The trainee journey > From first visit to renewal, with account and subscription states at each step. **Category:** Getting started · **Roles:** Admin · Head coach · Trainee · Assistant coach 1. **Visit the landing page** — The visitor meets the coach, the programs and real outcomes, reads the plans and FAQ, then reaches “Start now”. The job of this page is confidence before sign-up. 2. **Create an account** — Email or mobile number with an OTP, or social login. The account starts in pending_questionnaire, a verification link is sent, and terms and privacy acceptance are recorded. 3. **Complete the questionnaire** — Goal, experience, health, nutrition and sleep. Each section autosaves, required answers are enforced, and a medical-review flag appears when an answer needs it. 4. **Admin review** — The request lands in the admin queue with the questionnaire summary. The admin can request more information or reject it with a written reason the trainee receives. 5. **Approve and choose a plan** — The admin sets the plan, price and start date, assigns the coach and nutritionist, then raises an invoice and sends it to the trainee. 6. **Pay** — A Saudi payment gateway or a bank transfer. A successful payment activates the subscription automatically and issues the tax invoice; a manual transfer may need confirmation. 7. **Subscription activated** — The account moves to active, plan, workouts, nutrition and chat unlock, and the trainee sees a short guided tour of the dashboard. 8. **Trainee dashboard and plan** — Today cards for the workout, meals, water, steps, the next meeting and the subscription alert. The coach’s plan and meal plan, with every exercise explained before it is performed. 9. **Daily tracking and reports** — The trainee logs sets, meals and measurements and answers the weekly check-in. The coach sees adherence, adjusts the plan, and progress indicators update. 10. **Renewal** — Reminders at 7 days, 3 days and 1 day before expiry. After expiry the account becomes expired: history and reports stay, the live plan and chat close until renewal. > **Note** > > The admin's decision may be approval, a request for more information, or a rejection with a reason that reaches the trainee. A request can return for editing before it is approved. ## The full path, step by step | # | Step | Role | What the system does | Outcome | |---|---|---|---|---| | 1 | Visits the site and reads about the coach | Visitor | Tracks the visit, shows plans, exposes “Start now” | Starts sign-up | | 2 | Creates an account | Visitor | Creates the user, sends an OTP, records consent | `pending_questionnaire` | | 3 | Completes the questionnaire | Trainee | Autosaves, validates required answers, medical flag | `pending_review` | | 4 | Admin receives a notification | System | Notification plus queue entry | Request ready for review | | 5 | Admin reviews and decides | Admin | Approve / request info / reject with reason | `approved_unpaid` or `needs_info` | | 6 | Trainee pays | Trainee | Invoice, gateway, payment verification | `active` after success | | 7 | Subscription activates | System | Opens permissions and sends a welcome notice | Plan and dashboard available | | 8 | Trainee uses the platform daily | Trainee | Logs workouts, meals and measurements | Data and progress accumulate | | 9 | Coach reviews and adjusts | Coach | Notes plus a new plan version | Updated plan | | 10 | Expiry approaches, then renewal | System + trainee | 7/3/1-day reminders and a renewal invoice | Subscription continues | ## Expected timing per stage | Stage | Target | Owner | |---|---|---| | Account creation | Instant | System | | Questionnaire | 10–15 minutes | Trainee | | Admin review | Within one business day | Admin | | Invoice and payment | Instant, or one business day for a bank transfer | Trainee + system | | Subscription activation | Instant after payment confirmation | System | | First plan | Within 48 hours | Coach + nutritionist | | Weekly check-in | Every 7 days | Trainee + coach | | Renewal | 7 days before expiry | System + trainee | ## What happens behind the scenes - **A request is not a subscription:** the request lives in the review queue; the subscription starts only after approval and payment. - **Every state transition is recorded:** previous state, new state, actor and timestamp go into the activity log. - **Notifications follow events:** request created, approval, invoice, payment success, expiry warning and renewal. - **Permissions follow state:** an `expired` account can read history and reports only; the live plan and chat stay closed. - **Plans are versioned:** every coach edit creates a new version, and the previous one remains reviewable. **Trainee account states** | State | Meaning | |---|---| | `pending_questionnaire` | Registered but has not completed the questionnaire | | `pending_review` | Questionnaire complete, waiting for the admin | | `needs_info` | Admin requested more information | | `rejected` | Request rejected (with a reason) | | `approved_unpaid` | Approved, waiting for payment | | `active` | Subscription is live | | `expiring` | Seven days or fewer remain | | `expired` | Subscription ended (plan access restricted, history retained) | | `paused` | Subscription frozen | | `suspended` | Account suspended by the admin | > **Warning — Three separate lifecycles** > > Do not model the account, the registration request and the subscription as one status field. Each has its own lifecycle; see Binding operating rules. --- ## Roles & permissions > Five roles and exactly what each can see and do, with the full permission matrix and least-privilege rule. **Category:** Getting started · **Roles:** Admin · Head coach · Assistant coach · Nutritionist · Trainee · Technical owner Every person has exactly one primary role. Permissions are managed with `spatie/laravel-permission`, and the admin can customise what an assistant coach may do. | Permission | Technical owner | Admin / head coach | Assistant coach | Nutritionist | Trainee | |---|:-:|:-:|:-:|:-:|:-:| | Platform and infrastructure settings | ✅ | Own account settings only | ❌ | ❌ | ❌ | | Approve registration requests | ❌ | ✅ | ❌ | ❌ | ❌ | | Manage plans and pricing | ❌ | ✅ | ❌ | ❌ | ❌ | | View trainee records | ❌ | ✅ | Assigned only | Assigned only | Own record | | Build training programs | ❌ | ✅ | ✅ | ❌ | ❌ | | Build nutrition plans | ❌ | ✅ | ❌ | ✅ | ❌ | | Chat | ❌ | ✅ | ✅ | ✅ | With their coach | | Full reports | ❌ | ✅ | Their trainees | Their trainees | Own report | | Workspace activity log | ❌ | ✅ | Per permission | Per permission | Own activity | | Page and video tracking | ❌ | ✅ | ❌ | ❌ | ❌ | | Trainee invoices and payments | ❌ | ✅ | ❌ | ❌ | Own invoices | | AI assistant | ❌ | ✅ | ✅ | ✅ | ✅ (limited) | | Log daily data | — | — | — | — | ✅ | > **Warning — Least privilege** > > A trainee sees only their own data. An assistant coach or nutritionist sees only assigned trainees and only within their discipline. The technical owner runs infrastructure and integrations and does not, by default, access trainee health data. Any exceptional support access must be temporary, justified, documented and audited. **Role shortcuts** | Role | Start here | |---|---| | Admin / head coach | Admin dashboard | | Assistant coach | Trainee records | | Nutritionist | Nutrition & calories | | Trainee | Trainee dashboard | | Technical owner | Architecture | --- ## Website & landing page > Landing page sections, bilingual content, SEO and marketing pixels. **Category:** Getting started · **Roles:** Admin · Head coach The public interface a visitor sees before registering. It is fully managed from the admin dashboard — see Content & website. **Sections** | Section | Content | |---|---| | Hero | Headline, coach photo or video, “Start now” and “Download the app” | | About the coach | Bio, experience, certifications and qualifications | | About the platform | What it offers and how it works in four simple steps | | Services and programs | Training, nutrition, coaching, bodybuilding programs… | | Before / after | Trainee results, published only with written consent | | Plans and pricing | Monthly / 3-month / annual in SAR | | Testimonials | Ratings and quotes, moderated before publishing | | FAQ | Editable questions and answers | | App links | App Store / Google Play buttons and QR codes | | Contact and social | Instagram, TikTok, Snapchat, X, YouTube, WhatsApp | | Footer | Terms, privacy, refund policy | **Requirements** - Arabic (RTL) and English, with a language switch. - Fully responsive and comfortable on mobile. - SEO: titles and descriptions per page, Open Graph, `sitemap.xml`. - Fast loading: compressed WebP images and lazy loading. - Tracking pixels (Google Analytics, Meta Pixel, TikTok Pixel) toggled from settings, with cookie consent. > **Tip — Content is not code** > > Every section above is editable from the CMS in both languages. Publishing a change does not require a deployment. --- ## Sign-up & sign-in > Email or OTP sign-up, social login, 2FA and session/device management. **Category:** Getting started · **Roles:** Admin · Head coach · Trainee **Registration methods** - Email + password. - Mobile number + OTP (SMS or WhatsApp) — **recommended for the Saudi market**. - Google and Apple sign-in (Apple sign-in is required on iOS when social login exists). **Fields:** full name, mobile (+966), email, password, acceptance of terms and privacy policy. **Sign-in:** one form for every role; after authentication the user is routed by role. **Features** - Password reset by email or OTP. - Email and mobile verification. - Two-factor authentication: optional for trainees, **mandatory for admins**. - Rate limiting on failed attempts, with a temporary lockout. - Session and device management, with the ability to end sessions from “My account”. > **Warning — Payment is not activation** > > Returning from the payment provider's page does not activate a subscription. Activation happens only after a signed webhook is verified. See Payments & invoices. --- ## Intake questionnaire > The intake questionnaire, autosave rules and the medical-review flag. **Category:** Getting started · **Roles:** Admin · Head coach · Trainee Shown immediately after account creation. The trainee cannot move on until it is complete, and progress is saved automatically after each step so they can return later. **Questionnaire sections** | Section | Example questions | |---|---| | Basics | Age, sex, height, weight, city | | Goal | Fat loss · muscle gain · cutting · general fitness · rehabilitation · competition prep | | Numeric goal | Target weight and expected timeframe | | Training experience | Beginner / intermediate / advanced, years of training | | Training schedule | Days per week, session length, location (gym/home), available equipment | | Lifestyle | Work type, sleep hours, daily activity level | | Nutrition | Meals per day, food allergies, favourite and disliked foods, special diet | | Health (PAR-Q) | Chronic conditions, medication, previous injuries, surgeries, medical advice against exercise | | Supplements | What they currently use | | Starting photos (optional) | Front / side / back | | Requested program | Training · nutrition · coaching · everything | | Preferred plan | Monthly / 3-month / annual | | How did you hear about us? | Acquisition channel for reporting | **Rules** - Question types: single choice, multiple choice, number, text, image upload. - Questions are editable by the admin (add, remove, reorder, require) without code. - **Health status:** certain answers flag the request as “needs medical review” and show a clear alert to the admin. - **Consent:** the trainee confirms the information is accurate, understands the program does not replace medical advice, and consents to health-data processing. - After submission: “We received your request; we will review it within X hours.” > **Important — Safety first** > > A flagged health answer is never bulk-approved. It requires an individual review and, where appropriate, a request for medical clearance before any plan is published. --- ## Admin dashboard > The first screen after login: KPIs, latest requests, today’s meetings and alerts. **Category:** Getting started · **Roles:** Admin · Head coach The first screen after sign-in: your work at a glance. **KPI cards** | Card | Detail | |---|---| | New requests | Awaiting review, with a direct link | | Active subscriptions | Current count | | New subscriptions | This week / this month | | Expiring soon | Within 7 days, with a renewal action | | Expired | Requires follow-up | | Revenue | Today / this month / versus the previous period | | Inactive trainees | No activity for five days | | Unread messages | From trainees | **Sections** - **Latest requests:** a compact table with a “Review” action. - **Today and tomorrow's meetings:** pulled from Google Meet. - **Charts:** trainee growth, revenue, plan mix, goal mix. - **Attention alerts:** a trainee who has not complied, a pending invoice, a health-flagged request. - **Recent activity:** the latest ten events from the activity log. - **Quick actions:** new trainee · new program · send notification · schedule meeting. > **Tip — Design rule** > > Every number on this page must link to the filtered list that produced it. A KPI that cannot be explained in one click is a support ticket waiting to happen. --- ## Notification bell > The bell aggregates your events, with channels, filters and mark-all-read. **Category:** Getting started · **Roles:** Admin · Head coach · Assistant coach · Nutritionist The bell in the top bar aggregates what concerns you. Notifications travel through in-app (database), push (FCM), email and optionally WhatsApp, depending on type. **Admin notifications** | Event | Channel | |---|---| | A new trainee registered | Bell + email | | A trainee completed the questionnaire | Bell + push + email | | A request has a sensitive health answer | Bell + push | | Payment succeeded or failed | Bell + email | | Bank transfer awaiting confirmation | Bell + push | | Subscription expires in 7 / 3 / 1 days | Bell + email | | Subscription expired | Bell | | New message from a trainee | Bell + push | | Trainee has stopped logging | Bell (daily digest) | | Trainee reached their goal | Bell | | New review or complaint | Bell | Counters next to sidebar items show what is new in each area. There is a “Mark all as read” action and filtering by type. > **Note — Noise control** > > Notifications are grouped by trainee and type. A failed email does not create a duplicate in-app notification, and a retry never creates a duplicate payment or invoice. --- # Trainee management > Requests, records, plans, subscriptions and payments. ## Registration requests > Review registrations: approve, request info or reject, then set plan and price. **Category:** Trainee management · **Roles:** Admin · Head coach A single queue for everyone who completed the questionnaire and is waiting for a decision. **Queue columns:** name, goal, preferred plan, request date, health flag, status. **Review screen** - Full questionnaire answers, grouped by section, plus uploaded photos. - An automatic AI summary: “Beginner trainee, cutting goal, previous knee injury…” - The decision buttons: | Decision | What happens | |---|---| | **Approve** | The admin chooses the subscription term (monthly / 3 months / annual), the programs (training / nutrition / coaching), the responsible coach, and the final price or discount | | **Request information** | A message to the trainee listing exactly what is missing | | **Reject** | A reason is recorded and sent to the trainee | - On approval, the trainee receives a notification with the offer and a payment link. - The admin can add an internal note that the trainee never sees. - **Bulk approval is disabled for health-flagged requests.** > **Warning — Approval is not payment** > > Approval creates an unpaid subscription. Access is granted only after a verified payment or a documented manual payment recorded by the admin. --- ## Trainee records > The trainee record and its tabs and actions, from profile and subscription to measurements and activity. **Category:** Trainee management · **Roles:** Admin · Head coach · Assistant coach · Nutritionist **List:** search, filters (status, plan, coach, goal, expiry date), sorting, CSV export. **Trainee record (tabs)** | Tab | Content | |---|---| | Overview | Profile, goal, plan, coach, compliance rate, progress toward goal | | Questionnaire | Original answers, updatable when needed | | Subscription | Current plan and dates, plus previous subscriptions | | Training program | Current plan and its change history | | Nutrition plan | Current plan, calories and macros | | Measurements & photos | Weight, height, body circumferences, comparison photos | | Progress | Charts | | Sessions | Completed workout history | | Coach notes | Private notes and notes visible to the trainee | | Chat | The conversation with this trainee | | Invoices | Payments and receipts | | Activity | Their activity and page visits | **Actions:** edit profile, suspend or activate, pause the subscription, extend it, change coach, reset password, and impersonate — all written to the activity log. > **Important — Impersonation** > > “Sign in as trainee” is a support tool, not a convenience. It requires a reason, is time-limited, is visible to the trainee in their session history, and is audited. Health data is masked unless the admin has an explicit permission. --- ## Plans & subscriptions > Plans, pricing fields, coupons, and the subscription lifecycle, pauses and upgrades. **Category:** Trainee management · **Roles:** Admin · Head coach **Plans** are fully managed by the admin: | Field | Description | |---|---| | Name (Arabic/English) | For example, “Gold plan” | | Duration | 1 month · 3 months · 12 months (or custom) | | Price | SAR, inclusive or exclusive of VAT | | Promotional price | Optional, with an end date | | Included programs | Training / nutrition / weekly coaching / Meet calls / chat | | Limits | Meet sessions per month, plan edits | | AI assistant | Enabled or limited by a usage cap | | Status | Active / hidden | **Discount coupons:** percentage or fixed amount, expiry date, usage limit, restricted plans. **Subscription lifecycle** **States:** Admin approval → Awaiting payment → Active → Expiring → Expired → Paused → Cancelled > **Note — Key transitions** > > Renewal returns the subscription to **Active**. A pause stops the clock and extends the end date by the paused days. Missing the payment window cancels the request automatically. **Rules** - Renewal extends from the current end date if the subscription is still active, or from the payment date if it has expired. - Pausing extends the end date by the number of paused days. - Upgrading a plan: charge the pro-rata difference or start a new plan — an admin decision, recorded. - After expiry, the trainee keeps read-only access to history and reports; the live plan and chat are locked. - An optional grace period (for example, three days) can be configured. - Automatic renewal is a later phase, using stored cards. **Expiry alerts:** 7, 3 and 1 day before, and on the expiry day — to the trainee (push + WhatsApp/email) and to the admin. --- ## Payments & invoices > Saudi payment gateways, bank transfers, invoices, VAT and refunds. **Category:** Trainee management · **Roles:** Admin · Head coach · Trainee **Recommended Saudi gateways:** Moyasar, HyperPay or Tap — supporting **mada, Apple Pay, STC Pay and Visa/Mastercard**. Tamara or Tabby (instalments) can be added later. | Method | Mechanism | |---|---| | Online gateway | Payment from a link or the app, confirmed automatically by webhook | | Bank transfer | The trainee uploads a receipt; the admin confirms it manually | | Cash / external | Recorded manually by the admin with a note | **Invoices** - Generated automatically on every payment: sequential number, customer details, line items, VAT (**15%**), total, and a PDF in Arabic and English. - The coach's tax number and details come from settings. - **ZATCA e-invoicing:** the required phase is implemented according to the client's commercial status (see Open questions), including the QR code. - A credit note is issued on refund. - Refunds are recorded and appear in reporting. **Financial reporting:** revenue by period, plan and method; failed payments; refunds; CSV/Excel export. > **Important — App-store billing** > > Digital subscriptions inside an iOS app may fall under Apple's in-app payment rules. The common approach is to pay on the website or via a link, or to confirm that one-to-one personal training qualifies as a person-to-person service. **Review this before launch.** > **Note — Webhooks are the proof** > > Subscription activation happens only after a signed provider webhook is verified, with idempotency, and the amount, currency and order are matched. The browser return page is not proof of payment. --- # Training & nutrition > Exercises, programs, nutrition, measurements, habits and check-ins. ## Exercise library > The exercise database: fields, video and cues, substitutes and injury tags — every exercise explained to the trainee. **Category:** Training & nutrition · **Roles:** Admin · Head coach · Assistant coach · Trainee The exercise database from which every program is built. | Field | Description | |---|---| | Name (Arabic/English) | For example, “Barbell bench press” | | Primary and secondary muscles | Chest, back, legs… | | Exercise type | Strength · cardio · mobility · warm-up · stretch | | Equipment | Barbell, dumbbell, machine, bodyweight, none | | Level | Beginner / intermediate / advanced | | Demo video | Upload or link (unlisted YouTube/Vimeo) | | Images and execution steps | Written coaching cues | | Tips and common mistakes | Shown to the trainee | | Substitutes | Alternatives for injury or missing equipment | | Injured / contraindicated for | Injury tags (knee, shoulder, back) | **Features:** search and filters, CSV import/export, tags, and cloning from a starter library. ## What the trainee sees for every exercise Opening any exercise in their program gives a complete explanation — not just a name and a set count: | Element | What the trainee sees | |---|---| | Video | In-page player with replay and fullscreen | | Execution steps | Short numbered steps with an image for each key position | | Target muscles | Primary and secondary, with an illustration | | Tips | Three to five focus points before the first set | | Common mistakes | What to avoid and how to correct it | | Substitutes | An alternative with the same movement and less or more equipment | | Safety | A clear warning when the exercise carries an injury tag saved on the trainee | | “Tell the coach” | Opens a chat linked to that exercise when there is pain or confusion | > An exercise appears in a trainee's program only when the coach selects it or it comes from an approved template. Updating the explanation or video in the library updates every program that uses it. --- ## Workout programs > Build programs, weeks, days and sets, with templates, cloning and plan versions. **Category:** Training & nutrition · **Roles:** Admin · Head coach · Assistant coach · Trainee **Structure:** `program` → `weeks` → `training days` → `exercises` → `sets`. | Level | Fields | |---|---| | Program | Name, goal, length in weeks, level, days per week | | Day | Title (chest and triceps), warm-up, stretching, notes | | Exercise in a day | Sets, reps, suggested weight, rest, tempo, RPE | | Options | Supersets, drop sets, cardio (duration / distance / heart rate) | **Program sources** - **Templates:** a 4-day hypertrophy program, a cutting block, beginner fitness, home workouts… cloned and edited. - **Trainee-specific:** built from scratch or cloned from a template and adjusted. - **AI-assisted draft:** generated from the questionnaire and reviewed by the coach. It is never sent to the trainee before the coach approves it. **On the trainee side** - “Today's workout” with a start-session action. - Log every set: weight, reps and perceived effort. - Rest timer, exercise video, and skip or substitute an exercise (the coach is notified). - Finish the session: duration, session rating and a note for the coach. - **Personal records (PRs)** are captured automatically with an encouraging notification. - Progress per exercise: a chart of weight over time. **Plan versions:** every edit creates a new version with a reason; the previous version remains in history. > **Tip — Publishing rule** > > A published plan is never overwritten in place. Edits create a new version so the coach and trainee can always see what changed and when. --- ## Nutrition & calories > Saudi food database, calorie calculator, meal plans, swaps and shopping lists. **Category:** Training & nutrition · **Roles:** Admin · Head coach · Nutritionist · Trainee **Food database** | Field | Description | |---|---| | Name (Arabic/English) | Including common Saudi/Gulf foods (kabsa, mandi, dates, Arabic coffee…) | | Per 100 g | Calories, protein, carbs, fat, fibre | | Serving units | Gram, piece, tablespoon, cup | | Tags | Halal, vegetarian, gluten-free, allergens | | Barcode | Later phase | **Requirement calculator:** Mifflin-St Jeor for BMR × activity factor, then an adjustment for the goal (deficit or surplus) and a macro split (protein / carbs / fat). The coach can always override the numbers. **Meal plan** - Daily targets: calories, protein, carbs, fat, water. - Meals (breakfast, snack, lunch, dinner…) with foods and quantities calculated automatically. - **Substitutes** for every meal, matched on macros. - Allergies and disliked foods from the questionnaire (warning on conflict). - Ready templates for common plans (cutting, bulking, intermittent fasting…). - Different days (training/rest, or a weekly reference). - A **shopping list** generated automatically for the trainee. - Supplement plan and schedule. **On the trainee side** - Today's meals, with “eaten” or “swapped” markers. - Log an extra or off-plan meal (search the food database or enter it manually). - A daily bar showing remaining calories and macros. - Photograph a meal and send it to the coach (optional). - Log water. **Follow-up:** nutrition compliance = actual calories ÷ target calories, plus the number of compliant days. ## From the coach to the trainee dashboard 1. Pick a template or build a plan 2. Calculate calories and macros 3. Coach approval 4. Publish 5. Trainee logs 6. Weekly review - **Build:** the coach or nutritionist starts from a template or from the questionnaire, then edits meals and quantities. - **Review:** an automatic warning when the plan conflicts with an allergy, a disliked food or an unrealistic goal. - **Approve:** nothing appears to the trainee before the responsible coach approves it. - **Publish:** it appears immediately in the trainee dashboard and app, with meal reminders and the remaining-calories bar. - **Edit:** every change creates a new version with a reason; the previous version stays in history. - **Deliver:** the coach can share the plan as a PDF, sync it to Google Sheets (the “Meal plan” sheet) or send it in chat — see Analytics & Google Sheets. --- ## Measurements & progress > Weight, circumferences, body fat and progress photos, with strict photo privacy. **Category:** Training & nutrition · **Roles:** Admin · Head coach · Assistant coach · Trainee | Type | Detail | |---|---| | **Height and weight** | Logged periodically (weekly by default) | | **Body circumferences** | Chest, waist, hips, thigh, arm, calf, neck | | **Body composition** | Body-fat percentage and muscle mass (manual or from an InBody device) | | **BMI and estimated body fat** | Calculated automatically | | **Progress photos** | Front / side / back, before-and-after comparison, strict privacy | | **Performance tests** | Max reps, run time… | **Import (phase 2):** Apple Health / Google Health Connect for steps, sleep and heart rate. > **Important — Photo privacy** > > Progress photos are encrypted, never public, and are not used in the public “before/after” gallery without explicit written consent that can be withdrawn at any time. No public link ever exposes a progress photo or health file. --- ## Daily habits > Water, sleep, steps and mood, custom habits and streaks. **Category:** Training & nutrition · **Roles:** Trainee · Admin · Head coach Fast daily tracking from the trainee dashboard: - **Water:** a daily target with “+1 glass” buttons. - **Sleep:** hours and quality. - **Steps:** manual or synced from a health app. - **Mood / energy:** a 1–5 scale. - **Custom habits:** added by the coach (for example, take supplement, stretch for 10 minutes). - **Streak:** consecutive days with at least one log. - **Challenges, points and badges:** motivation mechanics, phase 3. > **Tip — Keep it to ten seconds** > > Habit logging is only useful if it is faster than ignoring it. One tap per habit, with sensible defaults and no mandatory notes. --- ## Check-ins & weekly review > Weekly check-ins, visible and private coach notes, and 4-week reviews. **Category:** Training & nutrition · **Roles:** Admin · Head coach · Assistant coach · Nutritionist · Trainee **Weekly check-in** - A short form is sent at the end of each week: weight, hunger, energy, sleep, compliance, optional photos, and questions for the coach. - The coach is notified of every new check-in. - The coach writes **feedback and instructions** (text, voice or short video), which appears on the trainee dashboard. - The coach can edit the plan directly from the check-in screen. **Coach notes:** two kinds — “visible to the trainee” and “private to the team”. **Periodic review:** every four weeks the platform compares against previous measurements automatically and produces a progress snapshot. > **Note — Coaching loop** > > The check-in is the most important retention tool in the product. It turns a silent subscription into a visible conversation at least once a week. --- # Trainee experience > The trainee dashboard and mobile app, screen by screen. ## Trainee dashboard > The trainee dashboard: today’s workout, meals, water, progress, coach feedback and subscription. **Category:** Trainee experience · **Roles:** Trainee · Admin · Head coach The first screen after sign-in for a trainee with an active subscription. **Today cards** - Today's workout (with a start action). - Today's meals and the calorie bar. - Water and steps. - The next meeting. - A subscription expiry reminder. - A new message or note from the coach. **Progress indicators** | Indicator | Meaning | |---|---| | Height | Latest measurement | | Weight | Current, starting, target and difference | | BMI | With classification | | Calories | Today / weekly average | | Training hours | This week / this month | | Training days | Days this month versus planned | | Compliance | Training + nutrition | | Progress toward goal | Calculated (see reports) | | Streak | Consecutive days | **Charts:** weight, circumferences, calories, training hours, weights lifted, weekly compliance. **Coach feedback:** a prominent card with the latest assessment and instructions, plus a history of previous feedback. **Trainee pages:** home · my program · my nutrition · measurements and photos · progress and reports · chat · my meetings · subscription and invoices · notifications · account. ## The trainee's daily loop 1. Subscription 2. Nutrition 3. Exercise library 4. Workout tracking 5. Coach plan 6. Google Sheet | Stage | What the trainee sees | What they do | |---|---|---| | **Subscription** | Current plan, renewal date, invoices | Renew or update payment details | | **Nutrition** | Today's meals, remaining calories and macros, substitutes, water | Log meals and swap items | | **Exercise library** | A full explanation of every exercise: video, steps, tips, mistakes, substitutes | Watch the explanation before training | | **Workout tracking** | Today's workout, sets, rest timer, personal records | Log every set and finish the session | | **Coach plan** | The approved training and nutrition plan and its updates | Review it and ask for clarification | | **Google Sheet** | A link to their private data sheet | Open the sheet to view their numbers | > **Warning — Expired subscription** > > An expired subscription turns the dashboard into read-only mode: history and reports remain available, while the live plan and chat are locked until renewal. --- ## Mobile app > The iOS/Android app: screens, push, offline workouts, biometrics and account deletion. **Category:** Trainee experience · **Roles:** Trainee · Admin · Head coach · Technical owner The app serves the **trainee** primarily, with a simplified coach edition. **Trainee app** | Screen | Function | |---|---| | Sign-in / registration / questionnaire | Same as the web | | Home | Today's workout, meals, water, reminders | | Workout | Run the session, timer, log sets, video | | Nutrition | Meals, food search, calories | | Measurements and photos | Entry and camera | | Progress | Charts and reports | | Chat | Text, images, voice, files | | Meetings | List and a Meet join button | | Notifications | Push + notification centre | | Subscription | Status and renewal | | Account | Profile, language, appearance, account deletion | **Mobile-specific requirements** - Push notifications through Firebase (FCM) + APNs. - Offline-first workout logging: log without a connection, sync later. - Dark mode and Arabic RTL. - Biometric sign-in (fingerprint / face). - Forced or optional update for old versions. - **In-app account deletion** (required by the app stores). - Links to the privacy policy and terms. - Coach edition: new requests, chat, trainees, alerts and quick approval. > **Important — Store compliance** > > In-app account deletion and a public privacy policy are mandatory. A digital subscription sold inside an iOS app may also trigger Apple's in-app purchase rules; confirm the billing route before submission. --- # Communication > Chat, meetings, notifications and the AI assistant. ## Chat > Direct messaging with text, media and voice, canned replies, response hours and moderation. **Category:** Communication · **Roles:** Admin · Head coach · Assistant coach · Nutritionist · Trainee Direct messaging between the trainee and their coach (and the nutritionist, when assigned). **Features** - Text, images, files, voice notes and short video. - Instant notifications, read receipts and a typing indicator. - Search inside the conversation. - Canned responses for the coach. - Attach an exercise, meal or measurement inside a message. - Response hours (for example, 9 am – 9 pm) shown to the trainee, with an automatic out-of-hours reply. - Chat is limited to an active subscription (read-only after expiry). - The admin can review conversations for moderation (disclosed in the privacy policy). - Report abuse and block. **Technology:** Laravel Reverb (WebSockets) or Pusher, with FCM for notifications outside the app. --- ## Meetings (Google Meet) > Google Meet sessions: creation, recurrence, reminders and attendance history. **Category:** Communication · **Roles:** Admin · Head coach · Assistant coach · Trainee **Creation:** scheduled by the coach or admin, or requested by the trainee (then approved by the coach). | Field | Description | |---|---| | Title and description | For example, “Weekly check-in call” | | Participants | One or more trainees | | Date and duration | With the time zone (Asia/Riyadh) | | Recurrence | Weekly, monthly | | Link | Generated automatically through the Google Calendar API | **What happens** - A Google Calendar event is created with a Meet link and an invitation is sent. - The meeting appears in the trainee and coach dashboards with a join button. - Reminders 24 hours, 1 hour and 10 minutes before (push + email/WhatsApp). - Plan limits: monthly meeting count. - Reschedule or cancel with notifications to both sides. - Attendance history (joined / did not join) and coach notes after the session. - **Coach availability:** the coach defines available slots so a trainee can book a free one. > **Note — Plan limits are enforced** > > Meeting limits are checked when a meeting is created, not after. An over-limit request offers an upgrade path instead of failing silently. --- ## Notifications & reminders > Central notifications: channels, templates, preferences and quiet hours. **Category:** Communication · **Roles:** Admin · Head coach · Trainee A central notification system. The admin can edit copy, enable or disable each type, and the trainee can set preferences. **Channels:** in-app · push · email · SMS · WhatsApp (optional). **Trainee notifications** | Event | Timing | |---|---| | Request approved + payment link | Immediately on approval | | Rejection / information request | Immediately | | Subscription activated | After payment | | **Meal time** | 15 minutes before each meal (configurable) | | **Today's workout** | At a time chosen by the trainee | | Water reminder | Every X hours | | Weight / measurement reminder | According to schedule | | Weekly check-in | On a set day | | **Google Meet session** | 24h / 1h / 10m before | | New coach reply | Immediately | | Plan updated | Immediately | | New personal record / badge | Immediately | | Coach instructions | Immediately | | Subscription expiring | 7 / 3 / 1 days | | Subscription expired | On the expiry day | | No log for several days (nudge) | After three inactive days | **Controls** - No noise: quiet hours chosen by the trainee. - Group repeated notifications. - A delivery log for every notification and its result. - Templates with variables such as `{trainee_name}` and `{meal_time}` in Arabic and English. --- ## AI assistant > The AI assistant for trainee and coach, with safety limits and AI governance. **Category:** Communication · **Roles:** Admin · Head coach · Assistant coach · Nutritionist · Trainee A language-model assistant (for example, Claude via API) that operates strictly within the user's role and permissions. **For the trainee** - Answers questions about their training and nutrition from **their own plan and data**. - Explains how to perform an exercise and suggests a substitute for an injury or missing equipment. - Calculates the calories of a meal and suggests swaps that fit their macros. - Summarises their week: “You completed 4 of 5 workouts; protein was behind on three days.” - States **progress toward the goal** and what would improve it most. - Reminds and motivates. **For the coach and admin** - A summary at the top of each trainee record: compliance, progress, risks. - Flags struggling trainees and suggests an intervention. - Suggests plan changes (a draft requiring coach approval). - Generates a draft program or meal plan from the questionnaire. - Drafts replies to trainee messages for the coach to review. - Summarises a new questionnaire before approval. - Answers operational questions: “Who expired this week?”, “Who is not complying?” **AI governance (important)** - It is not a doctor: a permanent disclaimer is shown; it does not diagnose or prescribe medication. - On alarming symptoms (chest pain, dizziness, acute injury) or eating-disorder signals, it recommends a specialist and alerts the coach. - **Safety boundaries:** a minimum calorie floor, and refusal of extreme diets, steroid doses or stimulant abuse. - Every suggestion for the coach requires approval before it reaches the trainee. - Conversations and actions are written to the activity log. - A daily usage cap per user, per plan, controls cost. - Unnecessary identifiers are removed before data is sent to the model. - The admin configures the name, tone, core instructions and knowledge base (the coach's philosophy and methods). --- # Performance & reporting > Google Sheets, reports, activity log and usage tracking. ## Analytics & Google Sheets > Sync each trainee’s data to a private Google Sheet with controlled sharing. **Category:** Performance & reporting · **Roles:** Admin · Head coach · Trainee · Technical owner **The idea:** each trainee has a private Google Sheet that their data syncs into, shared by link with the coach/admin and the trainee, so everyone can see the numbers in a familiar spreadsheet. **What syncs** | Sheet | Content | |---|---| | Summary | Goal, start, current, difference, progress percentage | | Measurements | Date, weight, circumferences, body fat | | Workouts | Sessions, sets and weights | | Nutrition | Daily calories and macros | | Habits | Water, sleep, steps | | Compliance | Weekly percentages | **How it works** - The platform database is the **source of truth**; sync runs from the platform to the sheet (one-way by default) to avoid conflicting data. - Sync uses the Google Sheets API (a service account), automatically after each change or on a schedule (hourly/daily). - A “Sync now” button and an “Open sheet” link live in the trainee record. - **Sharing permissions:** the trainee is a **Viewer**, the coach an **Editor**; sharing can be revoked automatically when the subscription ends. - Coach edits in the sheet can be imported in phase 2, with conflict-resolution rules. - A sync log records success, failure and row counts. - A combined export produces an admin sheet for all trainees. > The core analytics inside the platform (live charts) remain the primary interface; the sheet adds transparency and sharing. Health data is shared only through links restricted to specific accounts, never public links. ## Sharing the nutrition plan through Google Sheets In addition to tracking sheets, the platform can generate a **meal plan sheet** for each trainee: | Sheet | Content | |---|---| | Meal plan | Days of the week, meals, foods, quantities, calories and macros | | Substitutes | For each meal, the alternative and its macro equivalent | | Shopping list | Grouped by supermarket section for easier shopping | - A **“Export plan to Google Sheet”** action on the plan screen or in the trainee record. - The sheet updates automatically after each approved edit, with the last-sync timestamp visible. - Sharing: trainee Viewer, coach Editor; no public link is ever created. - A Google-free alternative: export a branded PDF or a compact image and send it through WhatsApp or chat. - When the subscription ends, sharing is revoked automatically (configurable). --- ## Reports > Trainee and admin reports, KPI formulas, and PDF/Excel export. **Category:** Performance & reporting · **Roles:** Admin · Head coach · Assistant coach · Nutritionist · Trainee A full reporting area that gives the trainee and the coach a view from day one to today. **Individual trainee report** | Section | Content | |---|---| | Summary | Period, goal, overall result | | **Before / after** | Weight, circumferences and body fat: start, end, **difference** and percentage | | Photos | A chronological comparison | | Charts | Weight, circumferences, calories, weights lifted, training hours | | Training | Sessions, days, hours, total volume, personal records | | Nutrition | Average calories and macros versus target, compliant days | | Habits | Water, sleep, steps | | Compliance | Weekly and monthly percentages | | **Coach feedback** | Notes and assessments in chronological order | | **AI recommendations** | What would help most | | Attendance | Meetings and attendance | **KPI formulas** (to be fixed with the client) | Metric | Formula | |---|---| | Training compliance | Sessions completed ÷ sessions planned × 100 | | Nutrition compliance | Days within ±10% of the calorie target ÷ logged days × 100 | | Progress toward goal | (start weight − current weight) ÷ (start weight − target weight) × 100 (inverted for muscle gain) | | Overall success score | Weighted: progress 40% + training compliance 30% + nutrition compliance 20% + habits 10% (configurable) | | Streak | Consecutive days with at least one log | **Admin reports** | Report | Content | |---|---| | Trainees | Growth, distribution (goal / plan / coach / city) | | Subscriptions | New, renewed, expired, retention, churn | | Revenue | By period, plan, method and coupon | | Conversion | Visitor → registration → questionnaire → approval → payment (funnel) | | Overall compliance | Who is complying and who is struggling | | Coaches | Coach workload, trainee satisfaction | | Content | Most-viewed exercises and videos | | Acquisition | Where trainees came from | **Export:** PDF (a branded template) and Excel/CSV. An automatic monthly report can be emailed or sent by WhatsApp to the trainee. > **Warning — Define every number** > > Every percentage in a dashboard or report must display its definition, period and denominator. A composite “success score” is an operational indicator, not a medical fact, and must never hide the underlying individual metrics. --- ## Activity log > An immutable audit trail: who did what, when, and before/after values. **Category:** Performance & reporting · **Roles:** Admin · Head coach An immutable record of everything that happens on the platform, visible to the admin. | Column | Description | |---|---| | Time | Precise date and time | | User | Who acted and in which role | | Event | Registration, sign-in, edit, delete, approval, payment, plan change… | | Object | The trainee, plan or invoice affected | | Details | **Before → after** values for edits | | Device and IP | Browser or mobile, plus IP | **Features:** search and filtering (user, type, period), export, alerts on critical events (deletion, permission change, sign-in from a new device), and a configurable retention period. **Technology:** `spatie/laravel-activitylog` or a custom implementation. > **Important — Never editable** > > The activity log is append-only. No role, including the admin, can edit or delete an entry through the product. Retention is handled by a controlled archival job, not by manual deletion. --- ## Page & video tracking > Page, dwell-time and video tracking with privacy safeguards. **Category:** Performance & reporting · **Roles:** Admin · Head coach · Technical owner The admin can see how each trainee behaves inside the platform and the app. **Recorded** | Data point | Detail | |---|---| | Page / screen visited | Name, path and time | | **Dwell time** | Actual active time, not just page open | | Visit count | Per page | | Sessions | Entry/exit, device, platform (web/iOS/Android) | | **Training video** | Watched? Percentage viewed, count, last position, completed? | | Exercises | Opened, session started, session completed | | Last seen | Most recent activity | **Admin view (inside the trainee record → “Activity” tab)** - A table of pages and time spent. - A timeline of the trainee's session. - A video list: watched / not watched / percentage. - A global view: most-visited pages, least-engaged trainees. - An alert: “Completed the exercise without watching its explanation video.” **Technology** - Lightweight events (a heartbeat every 15 seconds) sent to a dedicated API, batched. - Raw events are retained for a defined period (for example, 90 days), then aggregated into summary tables. - Video tracking through a player that emits `timeupdate` and `ended`. > This tracking is disclosed clearly in the privacy policy and terms and accepted by the trainee at registration. It is never used for health assessment or automated decisions against the trainee. --- # Platform operations > Team, settings, website, security and quality. ## Users & team > Team management: invites, roles, trainee assignment and account suspension. **Category:** Platform operations · **Roles:** Admin · Head coach · Technical owner - Add a user manually or invite them by link to their email. - Choose the role and customise permissions for assistants. - Assign trainees to assistant coaches. - Suspend or activate a user, reset their password and enforce 2FA. - View active sessions and end them. - Delete or anonymise an account according to the data-retention policy (see Security & compliance). --- ## Settings > All platform settings: branding, payments, email, Google, AI and mobile app. **Category:** Platform operations · **Roles:** Admin · Head coach · Technical owner | Section | Content | |---|---| | Branding | Name, logo, colours, fonts | | General | Time zone (Asia/Riyadh), language, currency (SAR), first day of the week | | Coach details | Bio, licences, tax number, address | | Payments | Gateway, bank account for transfers, tax | | Invoices | Numbering, logo, terms | | Email | SMTP/provider, templates | | Messaging | SMS and WhatsApp (UltraMsg/Twilio/Cloud API) | | Google | Calendar/Meet and Sheets (OAuth and service account) | | Notifications | Enable each type, channels and copy | | Questionnaire | Manage questions and sections | | AI | Enablement, settings, limits | | Meetings | Availability hours, default duration | | Mobile app | Versions, forced update, store links | | Security | 2FA, password policy, session lifetime | | Data retention | Retention and deletion periods | | Marketing tracking | Google Analytics, Meta Pixel, TikTok | | Backups | Schedule and restore | > **Warning — Owner separation** > > The technical owner manages infrastructure settings but does not see the coach's business data or trainee health data by default. Any support access is time-boxed, justified and audited. --- ## Content & website (CMS) > No-code website and content management: sections, pages, testimonials, FAQs and SEO. **Category:** Platform operations · **Roles:** Admin · Head coach Managed by the admin without code: - Home page sections (Arabic/English content, order, visibility). - Static pages: about, terms, privacy, refund policy. - Social links and app download links. - Results gallery (before/after, with consent). - Testimonials (approved before publishing). - FAQ. - Blog and articles (phase 3). - A “Contact us” form (delivered to the admin) and a newsletter. - SEO settings per page. - A media library (images, video, files) with size limits. --- ## Security, privacy & compliance > Technical security, PDPL compliance, consent, and access/export/deletion rights. **Category:** Platform operations · **Roles:** Admin · Head coach · Technical owner **Technical security** - Mandatory HTTPS and HSTS, plus security headers (CSP, X-Frame-Options…). - Hashed passwords (Argon2/bcrypt) and a password-strength policy. - 2FA for admins and rate limiting on sign-in. - Protection against CSRF, XSS and SQL injection (Laravel defaults, plus review). - API: Laravel Sanctum with short-lived tokens and refresh. - Uploads: type and size validation, storage outside the public path, and temporary signed URLs for private images and video. - Encryption at rest for sensitive health data and backups. - Card data is never stored in the platform; it is handled by the gateway only (PCI DSS is out of our scope). - Penetration testing and a vulnerability scan before launch. - Encrypted daily backups with restore testing. **Privacy and compliance** - **Saudi Personal Data Protection Law (PDPL):** health data is a sensitive category; explicit consent, purpose limitation, rights of access, correction and deletion, and breach notification. - **Hosting location:** preferably inside the Kingdom or in a jurisdiction compatible with data-transfer requirements (confirmed with the client's policy). - Privacy policy and terms in both languages, with consent at registration. - A clear clause covering activity tracking and the AI assistant. - A cookie policy with a consent banner. - The right to **export a trainee's data and delete their account** (from the app and web). - Admin access to health data is restricted by reason and logged. - A medical disclaimer: programs are general and do not replace medical advice. --- ## Performance & quality > Performance, scaling, queues, monitoring, testing and accessibility. **Category:** Platform operations · **Roles:** Admin · Head coach · Technical owner **Goal:** an organised, fast and reliable platform. - **Speed:** Redis for cache, sessions and queues; database indexing; eager loading to avoid N+1; pagination; a CDN for images and video. - **Video:** hosted on a dedicated service (Bunny Stream / Cloudflare Stream / S3 + CloudFront), not the main server. - **Heavy background work (queues):** notifications, Sheets sync, PDF generation and AI analysis, monitored with Laravel Horizon. - **Scalability:** split services when needed, read from a replica. - **Monitoring:** Sentry for errors, Laravel Telescope/Pulse for development and performance, and uptime alerts. - **Quality:** automated tests (Pest/PHPUnit) for subscription and payment paths, CI/CD, and a staging environment. - **Accessibility:** good colour contrast, screen-reader support and scalable text size. > **Tip — Definition of done** > > A feature is done when it works, is tested on the critical path, has a permission test, is documented here, and has been reviewed on mobile in both languages. --- # Technical reference > Architecture, data model, API, integrations and roadmap. ## Architecture > Stack, layers, packages, hosting and CI/CD. **Category:** Technical reference · **Roles:** Technical owner · Admin · Head coach | Layer | Recommended choice | |---|---| | Framework | Laravel 11/12 (PHP 8.3+) | | Front end | Blade + Livewire or Inertia (Vue/React) + Tailwind (RTL) | | Admin panel | Filament or a custom build | | Database | MySQL 8 / PostgreSQL | | Cache and queues | Redis + Horizon | | Real time | Laravel Reverb | | Files | S3-compatible (or encrypted local storage) | | Mobile | Flutter (or React Native) | | Push | Firebase Cloud Messaging | | Payments | Moyasar / HyperPay / Tap | | Email | SES / Mailgun / SMTP | | Hosting | Linux + Nginx, Docker containers (in-Kingdom cloud if required) | | CI/CD | GitHub Actions / GitLab CI | **Suggested packages:** `spatie/laravel-permission`, `spatie/laravel-activitylog`, `spatie/laravel-medialibrary`, `laravel/sanctum`, `spatie/laravel-backup`, `barryvdh/laravel-dompdf`, `maatwebsite/excel`, `google/apiclient`. **Internationalisation:** Laravel translation files plus translated content fields (`spatie/laravel-translatable`). --- ## Data model > Core tables grouped by module, with soft-delete and partitioning notes. **Category:** Technical reference · **Roles:** Technical owner · Admin · Head coach Core tables (initial schema): **Accounts and roles:** `users` · `roles` · `permissions` · `trainer_trainee_assignments` · `devices` (FCM tokens) · `user_sessions` **Questionnaire:** `questionnaire_sections` · `questionnaire_questions` · `questionnaire_responses` · `questionnaire_answers` **Trainees and requests:** `trainee_profiles` · `registration_requests` (status, decision, reason) · `trainer_notes` **Subscriptions and money:** `plans` · `plan_features` · `subscriptions` · `subscription_pauses` · `coupons` · `payments` · `invoices` · `invoice_items` · `refunds` · `bank_transfers` **Training:** `exercises` · `exercise_media` · `workout_programs` · `program_weeks` · `program_days` · `program_day_exercises` · `trainee_programs` (versions) · `workout_sessions` · `workout_sets` · `personal_records` **Nutrition:** `foods` · `food_servings` · `meal_plans` · `meal_plan_days` · `meals` · `meal_items` · `meal_substitutes` · `food_logs` · `supplement_plans` **Progress:** `body_measurements` · `progress_photos` · `habit_definitions` · `habit_logs` · `water_logs` · `sleep_logs` · `step_logs` · `weekly_checkins` · `trainer_feedback` **Communication:** `conversations` · `conversation_participants` · `messages` · `message_attachments` · `meetings` · `meeting_attendees` · `availability_slots` **Notifications:** `notifications` · `notification_templates` · `notification_preferences` · `notification_deliveries` **Tracking and reporting:** `activity_logs` · `page_views` · `page_view_sessions` · `video_views` · `reports` · `report_snapshots` · `sheet_syncs` **AI:** `ai_conversations` · `ai_messages` · `ai_settings` · `ai_usage` **Content and settings:** `settings` · `cms_sections` · `cms_pages` · `testimonials` · `faqs` · `contact_messages` · `newsletter_subscribers` · `media` **Notes** - Soft deletes for most tables. - Large event tables (`page_views`) are partitioned and aggregated periodically. - Dates are stored in UTC and displayed in Riyadh time. - A `tenant_id` column is not needed now; it can be added later if the product becomes multi-coach SaaS (see Open questions). --- ## API > The REST API: resource groups, examples, conventions and docs. **Category:** Technical reference · **Roles:** Technical owner · Admin · Head coach REST over JSON at `/api/v1/...`, documented with OpenAPI (Swagger/Scribe). | Group | Examples | |---|---| | Authentication | `POST /auth/register` · `/auth/login` · `/auth/otp` · `/auth/refresh` · `/auth/logout` | | Questionnaire | `GET /questionnaire` · `POST /questionnaire/answers` | | Subscription | `GET /plans` · `POST /subscriptions` · `GET /subscriptions/current` | | Payments | `POST /payments` · `POST /webhooks/payment` | | Training | `GET /me/program` · `POST /workouts/sessions` · `POST /workouts/sessions/{id}/sets` | | Nutrition | `GET /me/meal-plan` · `POST /food-logs` · `GET /foods?q=` | | Progress | `POST /measurements` · `POST /photos` · `GET /me/progress` · `GET /me/reports` | | Habits | `POST /habits/logs` · `POST /water` | | Chat | `GET /conversations` · `POST /messages` + a WebSocket channel | | Meetings | `GET /meetings` · `POST /meetings` | | Notifications | `GET /notifications` · `POST /devices` (FCM registration) | | Tracking | `POST /track/events` · `POST /track/video` | | Assistant | `POST /assistant/messages` | **Conventions:** consistent pagination, a consistent error envelope, `Accept-Language` for locale, and the app version in a header to support forced updates. --- ## Integrations > External integrations and their role: Google, payments, FCM, WhatsApp, ZATCA. **Category:** Technical reference · **Roles:** Technical owner · Admin · Head coach | Service | Use | Notes | |---|---|---| | **Google Calendar / Meet** | Create meetings and links | OAuth for the coach's account | | **Google Sheets** | Sync and share statistics and meal plans | Service account + sharing permissions | | **Payment gateway** | mada, Apple Pay, STC Pay, cards | Webhooks + signature verification | | **Firebase (FCM)** | Push | iOS requires an APNs key | | **WhatsApp** | Reminders and notifications | WhatsApp Cloud API (approved templates) or UltraMsg/Twilio | | **SMS / OTP** | Verification and alerts | An approved Saudi provider (for example, Unifonic) | | **Email** | Notifications and invoices | SES / Mailgun | | **AI provider** | Assistant | Claude API with privacy controls | | **Video hosting** | Exercise videos | Bunny / Cloudflare Stream | | **Apple Health / Health Connect** | Import steps and sleep | Phase 2 | | **ZATCA** | E-invoicing | Depending on the client's commercial status | | **Google/Meta/TikTok Analytics** | Marketing | After cookie consent | --- ## Roadmap & phases > Eight phases from discovery to launch and beyond, with acceptance criteria. **Category:** Technical reference · **Roles:** Admin · Head coach · Technical owner | Phase | Content | Indicative duration | |---|---|---| | **0 — Discovery and design** | Sign off this documentation, UX/UI, coach identity, database design | 2–3 weeks | | **1 — Core (web MVP)** | Landing page, sign-up and sign-in, questionnaire, admin requests, plans, subscription and payment, admin dashboard, basic notifications | 6–8 weeks | | **2 — Content and coaching** | Exercise library, programs, nutrition, measurements and photos, trainee dashboard, coach notes, basic reports | 6–8 weeks | | **3 — Communication and integration** | Chat, Google Meet, full notifications and reminders, Google Sheets | 4–5 weeks | | **4 — Intelligence and analytics** | AI assistant, advanced reports, activity log, page and video tracking | 4–5 weeks | | **5 — Mobile app** | Trainee + coach apps, push, offline, store publishing | 8–10 weeks (starts alongside phase 3) | | **6 — Launch** | Testing, security, performance, client training, soft launch then public launch | 2–3 weeks | | **7 — Later** | Auto-renewal, Tamara/Tabby, challenges and points, blog, wearables, multi-coach | By priority | > Durations are estimates for a small team and are re-baselined after design sign-off and team size are confirmed. **General acceptance criteria** - Every journey in The trainee journey works end to end on web and mobile. - Every notification in the table arrives through the specified channel at the specified time. - No user can see another user's data (automated permission tests). - Admin reports match the real numbers (reconciliation tests). - A published plan edit creates a version; a refund creates a credit note; a retried webhook never duplicates a payment. - Arabic RTL and English LTR both work on mobile and desktop sizes. > **Note — Change management** > > Any addition after sign-off is logged as a change request with: the requirement, the reason, affected screens, database and API impact, security impact, time and cost estimate, and an acceptance criterion. Items marked “later” are not included in the baseline price or timeline. --- ## Open questions > Business, content, technical and policy decisions needed before building. **Category:** Technical reference · **Roles:** Admin · Head coach · Technical owner **Business** 1. Is the platform **for one coach only**, or might it host other coaches later (SaaS)? This changes the architecture fundamentally. 2. How many trainees are expected in year one? Will assistant coaches or a nutritionist work with the coach? 3. Plans: what are the prices and what does each include? Is there a refund policy? 4. Is the coach VAT-registered, and is ZATCA integration required? 5. Are meetings included in every plan or sold separately? **Content** 6. Who prepares the exercise library and videos? Does the coach already own videos? 7. Is there an existing food database, or do we use a prepared one (including Saudi foods)? 8. Is the questionnaire ready, or should we propose it? **Technical** 9. Does the coach have a Google Workspace account (for Meet and Sheets)? 10. Which payment gateway is preferred, and is there a merchant account? 11. Are Apple Developer and Google Play accounts available? 12. Is the app for trainees only, or does the coach need it too? Is one codebase for iOS and Android acceptable? 13. Is in-Kingdom hosting required? **Policies** 14. What is the policy for publishing before/after photos? 15. Does the coach want to sell supplements or products (a store)? This is out of current scope. 16. May the AI assistant make direct plan changes, or suggestions only? (We recommend suggestions only.) --- ## Changelog > Documentation versions and material changes. **Category:** Technical reference · **Roles:** Admin · Head coach · Technical owner | Date | Change | |---|---| | 2026-11-06 | v2.0 documentation site: bilingual Arabic/English edition, per-module pages, role-based navigation, full-text search, dark mode, and the trainee loop (subscription → nutrition → exercise library → tracking → coach plan → Google Sheet) made explicit. | | 2026-11-03 | v2.0 unified index and navigation, clarified separation between the technical owner and the coach's business data, and added document scope, operating rules, acceptance criteria and change management. | | Earlier | Organised the core requirements and added modules: measurements and photos, habits, weekly check-ins, exercise library, calorie calculator, AI governance, PDPL compliance and the delivery roadmap. | --- # Appendices > Additions beyond the brief and binding operating rules. ## Additions to the brief > Modules added beyond the original brief, and why. **Category:** Appendices · **Roles:** Admin · Head coach · Technical owner For review with the client, these modules were **added** from discovery and were not explicitly in the original brief: | Addition | Why | |---|---| | Health questionnaire (PAR-Q) and medical consent | Trainee safety and the coach's legal protection | | Exercise library with videos and substitutes | The foundation of any program | | Calorie and macro calculator with Saudi foods | Speeds up the coach's work | | Body measurements, progress photos and before/after | The heart of reporting | | Water, sleep and step tracking | A fuller picture of compliance | | Weekly check-in | The most important coaching tool between sessions | | Coach availability and booking | Organised scheduling | | Discount coupons, grace period and pauses | Subscription flexibility | | Bank transfer and tax invoicing (ZATCA) | Saudi market requirements | | Assistant coaches and a nutritionist | Business growth | | Personal records, streaks and badges | Trainee motivation | | Apple Health / Health Connect sync | Automatic data without manual entry | | Reviews, testimonials, FAQ and blog | Marketing and trust | | Device and session management, 2FA | Security | | Backups and data export/deletion rights | PDPL and app-store compliance | --- ## Binding operating rules > Rules to lock before development: states, payments, permissions and tracking. **Category:** Appendices · **Roles:** Admin · Head coach · Technical owner ### 1. Request and subscription states are separate Do not represent the account state, the registration-request state and the subscription state in one field. Each has an independent lifecycle: - Account: active, unverified, suspended, deleted/scheduled for deletion. - Request: draft, awaiting questionnaire, awaiting review, needs information, approved, rejected. - Subscription: awaiting payment, active, expiring, paused, expired, cancelled, partially/fully refunded. ### 2. Payment does not activate a subscription on browser return Activation happens only after a signed webhook from the payment provider is verified, with idempotency and a match on amount, currency and order. The browser return page is not proof of payment. ### 3. Google Sheets permissions - Never create public links for files containing health data or measurements. - Share with specific accounts, with the ability to revoke. - The trainee gets Viewer by default, never Editor without a clear decision. - File creation, sharing, revocation and sync are logged. - A failed sync never stops the platform or changes database data. ### 4. Tracking and analytics - Collect the minimum necessary usage events, with clear notice and appropriate consent under the privacy policy. - Page or video tracking is never used for health assessment or automated decisions against the trainee. - “Active watch time” must be defined technically, including inactive tabs and connection loss. ### 5. AI assistant - Does not diagnose medical conditions, prescribe treatment, or recommend medications or steroid doses. - Does not modify a published plan or send sensitive advice without the responsible coach's approval. - States that calorie calculations and projections are estimates and may differ from actual measurement. - Shows the data sources and period behind an analysis, with the ability to correct the data. - Removes unnecessary personal data before sending it to the model provider, and defines conversation retention. ### 6. KPI definitions Every percentage in a dashboard or report must show its definition, period and denominator. A single “success score” is not a medical fact; it is a configurable operational indicator and must not hide the individual metrics. ### 7. Detailed acceptance criteria **Checklist** - A trainee cannot access another trainee's record by changing an ID in a URL or API call. - An assistant coach cannot see an unassigned trainee. - A nutritionist cannot edit a training program without explicit permission. - A subscription is never activated without valid payment proof or a documented manual payment. - Every edit to a published plan stores a previous version, the editor and the timestamp. - No progress photo or private health file is reachable through a public link. - A notification can be re-sent without creating a duplicate payment or invoice. - A backup can be restored in a test environment and its files and database verified. - Core interfaces work in Arabic RTL and English LTR, on mobile and desktop. - Core journeys are tested automatically: registration, approval, payment, activation, workout logging, meal logging, weekly check-in, renewal and expiry. ### 8. Change management Any addition after this document is approved is logged as a change request containing: the requirement, the reason for change, affected screens, impact on the database and API, security impact, time and cost estimate, and an acceptance criterion. Items listed as “later” are not a commitment within the baseline price or timeline. --- © 2026 AZVYRA · Built by BYTE ON · All rights reserved.