duke6290/FormAI-Coach

Where biomechanics meets artistry, and every rep becomes a rehearsal for greatness.

Welcome to FormAI Sanctuary, a next-generation computational movement studio that transforms how human beings relate to their own bodies. While its spiritual ancestor, FormAI, introduced the world to AI-guided personal training, FormAI Sanctuary goes further — it does not merely watch your form; it composes it. Think of it as a master choreographer, a biomechanics professor, and a patient mentor fused into a single, ambient intelligence that lives quietly in your browser, your phone, and your wearable ecosystem.

This repository houses the complete architecture of the Sanctuary: a real-time pose estimation engine, a procedural feedback composer, an adaptive progression planner, and a beautifully responsive multisensory interface. It is designed for athletes, physiotherapy patients, dancers, rehabilitation specialists, weekend warriors, and anyone who has ever wondered, "Am I actually doing this exercise correctly?"

The answer, from now on, lives here.

• Overview — The Vision Behind the Sanctuary
• Why FormAI Sanctuary Exists
• Core Feature Constellation
• The Movement Intelligence Layer
• User Experience Philosophy
• Multilingual & Accessibility Charter
• Adaptive Coaching Scenarios
• Technology Stack
• Repository Anatomy
• Roadmap for 2026 and Beyond
• Frequently Explored Questions
• Community & Contribution
• Support Promise
• Disclaimer
• License

Most fitness software counts repetitions. A rare few estimate calories. Almost none actually understand movement quality — the subtle interplay between joint angles, tempo, symmetry, and muscular intent that separates a productive session from an injury waiting to happen.

FormAI Sanctuary was born from a frustration shared by coaches, clinicians, and athletes alike: cameras became smart, but coaching did not. We asked ourselves a heretical question:

What if your device could describe — in plain human language — exactly how your left knee drifted three degrees too far inward on rep fourteen of your squat, and why that matters for your patellar tendon?

The Sanctuary answers that question in milliseconds, continuously, and without judgment. It is not a judge. It is a mirror that speaks.

Every feature below is engineered to dissolve friction between the human body and the digital coach. Read them as invitations, not specifications.

• Real-Time Pose Cartography — A dense skeletal mesh is reconstructed from your camera feed at up to 60 frames per second, giving instant awareness of joint trajectories and limb relationships.
• Tempo Choreography Engine — Detects eccentric, concentric, and isometric phases, then narrates pacing back to you in elegant, human language.
• Symmetry Sentinel — Highlights left/right imbalances as they emerge, not after the fact, so compensations never become habits.
• Adaptive Progression Composer — Rebuilds the next session dynamically based on today's performance, fatigue signals, and your declared goals.
• Responsive Interface, Everywhere — A fluid layout that restructures itself gracefully across ultrawide monitors, laptops, tablets, foldables, and wrist devices.
• Multilingual Conscience — Coaching cues and interface copy are localized for global audiences, with tone-appropriate phrasing per culture.
• Ambient Session Memory — Summaries are stored locally so you can watch progress bloom over weeks rather than increments.
• Voice & Text Duality — Choose a warm spoken coach, a silent textual whisper, or both.
• Safety Envelope Detection — Recognizes dangerous joint configurations and interrupts with clear, calm guidance.
• Offline Humility Mode — Delivers core feedback without any network dependency, because your training should not hinge on a signal bar.
• Wearable Whispers — Pulse rate, HRV, and motion sensors from compatible wearables enrich the coaching context.
• Coach Console — Professionals can observe multiple clients in a live roster with annotated overlays.
• Session Storytelling — Turns raw metrics into a readable narrative — a paragraph, not a spreadsheet.

At the heart of the Sanctuary lives what we call the Movement Intelligence Layer (MIL). It is a layered system of perception, interpretation, and expression:

1. Perception Tier — Captures frames, extracts landmarks, smooths noise, and maintains a temporal identity of each joint.
2. Interpretation Tier — Compares the observed motion against a library of canonical templates, but with tolerance — because no two bodies are identical.
3. Expression Tier — Converts classification into a coaching cue. This is where the Sanctuary's voice lives: concise, kind, and specific.

The MIL is deliberately modular. Researchers can swap classifiers, therapists can author custom templates, and developers can extend expression vocabularies without touching perception code.

FormAI Sanctuary refuses the aesthetic of a control panel. Instead, the interface borrows from ateliers, studios, and rehearsal halls:

• Quiet Defaults — The system speaks only when something meaningful changes.
• Calm Color Semantics — Warm hues for encouragement, cool hues for neutral observation, and a gentle amber for attention.
• Typography With Breath — Generous line height, abundant whitespace, and clear hierarchy so the eye never fights the interface.
• Motion That Supports Meaning — Transitions illuminate bone-joint overlays rather than distracting from them.
• No Shame Architecture — The feedback tone is deliberately non-punitive. Nothing in the Sanctuary says "wrong." It says "here is another path."

The Sanctuary treats language as a first-class architectural concern, not a translation afterthought.

• Localized Coaching Cues — Idiomatic phrasings are authored per language, not machine-translated blindly.
• Right-to-Left Harmony — Interfaces mirror cleanly for Arabic, Hebrew, and Farsi.
• Dyslexia-Friendly Reading Mode — Optional spacing and font treatment for comfortable reading.
• High-Contrast Practice Mode — Designed for gyms with harsh lighting or users with visual sensitivities.
• Screen Reader Narration — All dynamic feedback is announced with ARIA-compliant labels.
• Keyboard-Only Rituals — Every action is reachable without a mouse.
• Subtitled Audio Cues — For shared spaces and silent environments.

The Sanctuary flourishes in a wide range of scenarios. A brief sampler:

• Strength Athletes — Refining squat depth, bench bar path, and deadlift bracing mechanics.
• Rehabilitation Patients — Guiding shoulder rotations or gait retraining with clinician-authored templates.
• Yoga & Mobility Practitioners — Observing alignment shifts during long holds.
• Dancers & Performers — Choreography rehearsal with symmetry and tempo overlays.
• Remote Coaching Practices — Trainers sharing annotated clips with clients across time zones.
• Workspace Ergonomics Studies — Understanding postural drift across a workday.

The Sanctuary is assembled from carefully chosen building blocks, each picked for durability rather than novelty:

• Runtime Layer — Modern JavaScript/TypeScript for the client, with a lightweight Node-compatible service layer.
• Vision Pipeline — WebGL-accelerated landmark inference with adaptive frame skipping on constrained hardware.
• State Architecture — Deterministic session state modeled as an event-sourced timeline for full replayability.
• Data Layer — Local-first storage using IndexedDB, with optional encrypted sync to a self-hosted endpoint.
• Styling System — Token-based design system enabling themes, contrast modes, and layout inversions.
• Build & Tooling — Reproducible builds with bundler-agnostic configuration and lightweight test harness.
• Telemetry Discipline — Opt-in only; never collects video, and never streams frames off the device.

A guided map of the monorepo:

• /core — The Movement Intelligence Layer, pose understanding, and template library.
• /coach — Progression composer, cue generator, and session storytelling.
• /ui — Responsive components, design tokens, and multilingual resource bundles.
• /integrations — Adapters for wearables, camera vendors, and clinician export formats.
• /docs — Architectural essays, contribution guides, and glossaries.
• /research — Notebooks and reproducibility artifacts for internal studies.
• /samples — Illuminating examples that illustrate extension points.

The Sanctuary is deliberately ambitious but responsibly paced.

• Q1 2026 — Public beta of the revised Movement Intelligence Layer with 30 canonical movement templates.
• Q2 2026 — Multilingual release covering 12 primary languages with culturally reviewed coaching cues.
• Q3 2026 — Coach Console general availability with multi-client observation mode.
• Q4 2026 — Wearable fusion, session storytelling, and customizable cue authoring for clinicians.
• 2027 Vision — Community-authored movement template marketplace and open research datasets.

• Does the Sanctuary store my video? No. Frames are processed on your device and discarded after inference.
• Does it work without internet access? Yes; core feedback runs fully offline.
• Can clinicians define their own movement templates? Absolutely; the template format is documented and open.
• Is it usable on phones? Yes; the responsive UI adapts gracefully from wide monitors to handheld devices.
• Is there a cost? The project is openly licensed for personal, research, and clinical use.
• Can I contribute a translation? Yes; translations live in structured resource bundles in /ui.
• Which wearables are supported? A growing roster; the integration layer is adapter-based.

The Sanctuary is stronger when diverse minds arrive with diverse movement experiences. Contributions are welcome in many forms:

• Movement Templates — Author new exercises with clearly annotated joint constraints.
• Translations — Provide idiomatic coaching cues in your language, not literal translations.
• Design Tokens — Improve contrast modes, spacing scales, and theming.
• Research — Share reproducible studies on movement quality and feedback efficacy.
• Documentation — Clarify, illustrate, and translate the docs.
• Accessibility Testing — Stress-test screen reader flows and keyboard-only navigation.

We ask contributors to be patient, precise, and kind — the same qualities the Sanctuary aspires to embody.

The Sanctuary is accompanied by a 24/7 support promise for enterprise and clinical deployments, with community-driven assistance available around the clock for the broader community. Whether you are debugging a camera compatibility issue at 3 AM in Tokyo or writing a movement template during a quiet afternoon in Lisbon, someone is reachable.

Support channels include in-app guidance, structured issue templates, and a living knowledge base that grows alongside the project.

FormAI Sanctuary is a computational coaching aid, not a medical device. The feedback it provides is informational and educational in nature. It does not diagnose, treat, cure, or prevent any disease or injury. Always consult a qualified healthcare professional before beginning a new training regimen, particularly if you have a pre-existing condition, are pregnant, or are recovering from surgery.

By using this software, you acknowledge that any physical activity carries inherent risk, and that you are responsible for your own safety, judgment, and form. The maintainers, contributors, and affiliated organizations accept no liability for injuries, damages, or losses arising from the use of this project. Use it as a partner in your practice — never as a replacement for professional human oversight when such oversight is warranted.

FormAI Sanctuary is released under the MIT License. You are welcome to study, adapt, and extend the codebase, provided that the license terms are honored.

A full copy of the license text accompanies this repository and can be reviewed at the canonical reference: MIT License.

Copyright (c) 2026 FormAI Sanctuary Contributors.

Form, in the end, is not a constraint. It is a doorway — a way of moving through the world with greater ease, longevity, and joy. The Sanctuary exists to hold that door open for anyone willing to walk through it.

Train gently. Move deliberately. Return often.