Shakti Domain — Features

Shakti — Physical Discipline and Movement Intelligence Platform

Shakti (the Hindu concept of primordial cosmic energy — the dynamic force underlying all of existence) is a comprehensive fitness, wellness, and movement intelligence platform covering every dimension of physical training. The platform spans yoga, strength training, martial arts, combat sports, mobility, biometric tracking, AI-powered form analysis, gamification, community, instructor tools, studio management, and state-of-the-art features including velocity-based training, genetic personalization, and VR fitness.

Shakti is a pure library domain — 28 self-contained TypeScript libraries under libs/shakti/, with no standalone applications or services. Each library is a typed domain knowledge base and configuration registry rather than a running service. The feature map below describes the capabilities those libraries model, organized by the area of the platform each set of libraries serves.

1. Core Platform#

The core platform is the foundation everything else builds on. @shakti/core provides the type system, runtime validation, database schema, event bus, and authorization logic that all other Shakti libraries reference. A new engineer should read this section first — it defines the vocabulary (types, enums, error codes) used throughout the rest of the domain.

• Domain type system: Comprehensive TypeScript types covering movement patterns, anatomy (76 named muscles, 13 joints with range-of-motion norms), exercises, workouts, programs, sessions, equipment (a 75-item catalog), and training value objects (tempo, rep ranges, set/rest configurations, load prescriptions, progression models) — with a Result<T, E> outcome type for domain operations.
• Validation schemas: Runtime validation for every platform schema (techniques, exercises, workouts, programs, sessions, practitioners, belt ranks, achievements, challenges, instructors, classes, goals) via hand-written validate* functions that return a list of error messages. Validation is plain TypeScript — no third-party schema library.
• Database schema: A declarative schema (11 tables: practitioners, disciplines, discipline styles, techniques, exercises, programs, sessions, personal records, achievements, belt ranks, streaks) for the shakti PostgreSQL schema, defined as TableDef data with foreign keys, check constraints, and indexes, plus a generator that emits the corresponding DDL.
• Domain event system: An in-process event bus for cross-module communication. It supports 20 typed event types — including session.started, session.completed, exercise.performed, personal_record.achieved, form_analysis.completed, achievement.unlocked, and streak.milestone — with batching, a dead-letter queue, replay, versioning, and metrics. The bus is part of the @shakti/core foundation.
• Authorization: Role-based access control with seven roles (practitioner, instructor, studio owner, admin, moderator, content creator, guest), 16 resource types, and per-role permission tables evaluated by a checkPermission function. Includes JWT-claim and API-key validation helpers. This is authorization logic only — it performs no token signing or session storage.

2. Yoga and Mindfulness#

A complete yoga instruction system covering asanas, breathwork, sequencing, multiple styles, meditation, and Ayurvedic personalization (@shakti/yoga).

Asana Library#

An asana is a yoga posture. The term comes from Sanskrit and literally means "seat" or "posture" — though in modern yoga it refers to any of the physical poses practiced.

• Complete asana database: Every major yoga pose with Sanskrit and English names, alignment cues (specific instructions for how to position the body), muscle engagement maps, and difficulty ratings.
• Contraindication tracking: Each asana is annotated with contraindications — conditions under which the pose should be avoided or modified, such as specific injuries, pregnancy, or cardiovascular conditions.
• Modification variants: Beginner, intermediate, and advanced modifications for each pose with prop suggestions (blocks, straps, bolsters), ensuring the practice is accessible at every level.
• Muscle group targeting: Detailed muscle engagement maps showing which muscles are being stretched, strengthened, or stabilized in each pose — useful for sequencing and for practitioners recovering from injury.

Pranayama (Breathwork)#

Pranayama is the practice of conscious breath control. "Prana" means life force; "ayama" means extension. These are structured breathing exercises that directly influence the nervous system.

• Breathing technique library: Comprehensive breathwork techniques with physiological descriptions and timing patterns:
  • Ujjayi ("victorious breath") — constricted throat breathing that creates an audible ocean sound, warming the body and focusing the mind
  • Nadi Shodhana (alternate nostril breathing) — alternates breath between nostrils to balance left and right hemispheres
  • Kapalabhati ("skull shining") — rapid forceful exhalations that energize and clear the respiratory system
  • Bhramari (humming bee breath) — humming exhalation that activates the vagus nerve for rapid calming
  • Box Breathing — four-count inhale/hold/exhale/hold cycle for stress management
• Physiological effects documentation: Documented effects of each technique (calming, energizing, balancing) for informed selection.
• Guided timing patterns: Configurable inhale/hold/exhale ratio configurations for different experience levels.

Sequence Building#

A yoga sequence is a series of asanas arranged in a particular order. Good sequencing follows pedagogical principles: warm-up, progressive intensification, peak poses, and cool-down.

• Intelligent sequencing: Automatically order poses with logical transitions, warm-up progression, peak poses, and cool-down — following traditional sequencing principles.
• Style-specific sequences: Generate sequences appropriate to specific yoga styles (Vinyasa flow, Ashtanga series ordering, Yin long holds, Restorative with props).
• Duration targeting: Build sequences that fit specified time durations while maintaining pedagogical completeness — never ending abruptly mid-sequence.
• Custom sequence creation: Drag-and-drop sequence builder with transition validation, allowing instructors to design custom sequences.

Yoga Styles#

Shakti models eight distinct yoga styles, each with its own sequencing logic, pacing, and pedagogical rules. The platform supports all of them rather than treating yoga as a single undifferentiated discipline.

• Vinyasa: Flowing breath-synchronized sequences where movement and breath move together, with creative transitions between poses.
• Ashtanga: Traditional series with correct pose ordering and explicit progression criteria — practitioners advance to the next pose only when the previous one is mastered.
• Yin: Long-held passive poses (3–5 minutes) targeting the connective tissue and fascia rather than muscles, with fascia-specific guidance.
• Restorative: Prop-supported gentle poses held for 5–20 minutes for deep parasympathetic activation — often used for stress recovery.
• Kundalini: Kriyas (complete exercise sets) integrating mantra, specific breathwork, and meditation — focused on awakening energy through the spine.
• Bikram/Hot yoga: The classic 26-posture Bikram sequence practiced in a heated room, with guidance on heat considerations and hydration.
• Hatha: Classical, slower-paced yoga focusing on foundational postures held for several breaths, alignment precision, and breath awareness — the tradition from which most modern yoga styles derive. Suitable for beginners and practitioners seeking a grounded, less vigorous practice.
• Power yoga: An athletically demanding, fitness-oriented style derived from Ashtanga Vinyasa, emphasizing strength, endurance, and calorie burn. Sequences are not fixed and vary by instructor, making it adaptable to different training goals.

Meditation and Ayurveda#

• Guided meditation frameworks: Session templates with instructions, ambient sound integration, and timer management for different meditation styles (breath, body scan, mantra, visualization).
• Ayurvedic constitution assessment: Dosha questionnaire determining the user's constitution (Vata — movement/air, Pitta — transformation/fire, Kapha — structure/earth) with personalized practice recommendations. Ayurveda is the ancient Indian system of medicine that classifies individual constitution into these three fundamental energies.
• Practice recommendations: Yoga and lifestyle recommendations tailored to individual dosha constitution and seasonal considerations (Vata-pacifying practices are different from Pitta-pacifying practices).

3. Strength and Conditioning#

Comprehensive exercise science and programming for resistance training at every level (@shakti/strength). The library goes far beyond a basic exercise list — it encodes periodization theory, 1RM estimation algorithms, and complete multi-week program templates for different training philosophies.

Exercise Database#

• Comprehensive exercise library: Hundreds of exercises with primary and secondary muscle group targeting, equipment requirements, detailed form descriptions, and common error flags.
• Compound lifts analysis: In-depth coverage of the squat, deadlift, bench press, and overhead press with biomechanical analysis of joint angles, bar path, and muscular recruitment at each phase.
• Olympic weightlifting: Complete snatch and clean-and-jerk technique libraries with progression sequences — from foundational pulling positions through full lifts — with breakdowns of each technical phase.
• Calisthenics progressions: Bodyweight exercise skill trees from beginner to advanced, covering handstand progressions, muscle-up progressions, front lever and back lever, planche development, and more.

Programming#

The programming module models the proven periodization systems used by competitive strength athletes and evidence-based coaches, so that generated programs follow real training theory rather than generic templates.

• Program templates: Proven evidence-based programs: 5/3/1 (Jim Wendler's percentage-based wave loading), Starting Strength (linear progression for beginners), GZCL Method (tiered volume/intensity), Push-Pull-Legs, Upper/Lower splits, full-body 3x/week.
• Powerlifting meet prep: Competition preparation with peaking cycles (short-term intensity increase approaching competition), attempt selection strategy, and meet-day warm-up protocols.
• Hypertrophy optimization: Volume, intensity, and frequency optimization for maximum muscle growth, incorporating muscle protein synthesis research (minimum effective volume, maximum adaptive volume).
• Periodization: Linear periodization (weekly progress), undulating periodization (varying intensity within a week), and block periodization (dedicated phases for accumulation, intensification, and realization), with auto-regulated deload detection.

4. Martial Arts#

Comprehensive technique library covering striking, grappling, traditional forms, weapons, and rank progression (@shakti/martial-arts). This library models martial arts as a complete progressive curriculum rather than a flat list of techniques — prerequisite chains, rank requirements, and sparring formats are all first-class concepts.

Technique Database#

• Striking techniques: Punches (jab, cross, hook, uppercut), kicks (roundhouse, front kick, side kick, spinning heel kick), elbows, and knees — each with biomechanical analysis, chamber/extension/retraction phases, common errors, and drilling progressions.
• Grappling techniques: Full curriculum covering takedowns, clinch control, ground positions (mount, guard, side control, back control), submissions (chokes, joint locks), escapes, sweeps, and transitions.
• MMA integration: Combined striking and grappling curriculum for mixed martial arts — including transitions between ranges (stand-up to clinch to ground), cage/fence work, and rule set considerations.
• Traditional forms: Kata (karate), poomsae (taekwondo), and taolu (kung fu) with step-by-step breakdowns, bunkai (application explanations for karate kata), and video reference alignment.
• Weapons training: Bo staff, nunchaku, sword forms, and other traditional weapons with safety protocols, handling fundamentals, and style-specific forms.

Progression and Competition#

• Belt and rank tracking: Multi-style rank progression with grading criteria per rank, testing requirements, and time-in-grade requirements — covering karate, taekwondo, BJJ, judo, and other arts.
• Sparring management: Session management with rules configuration (points, time, equipment), scoring, and partner matchmaking by rank and size.
• Technique difficulty progression: Progressive difficulty curves from foundational techniques to advanced combinations, ensuring students develop prerequisite skills before attempting complex techniques.

5. Combat Sports#

Sport-specific training modules for competitive combat disciplines (@shakti/combat-sports). Where the martial-arts library covers techniques as a progressive curriculum, this library focuses on the sport preparation side: round-based conditioning, training camps, and competition-specific strategies.

• Boxing: Structured bag work sequences, mitt work combinations, footwork drills, defensive head movement, ring tactics, and round-based conditioning.
• Kickboxing: Technique and conditioning programs with round-based timing, leg kick integration, and style-specific strategies (Dutch style, K-1 rules, point fighting).
• Muay Thai: The "Art of Eight Limbs" — integration of fists, elbows, knees, and shins. Clinch work (the dominant Thai boxing position for elbows and knees), elbow and knee technique library, and traditional conditioning (pad work, heavy bag, shadowboxing, rope skipping).
• Wrestling: Takedown entries (singles, doubles, high crotch), pins, scrambles, top position control, and wrestling-specific conditioning circuits used by elite wrestlers.
• MMA training: Fight preparation including skill integration across ranges, sport-specific conditioning (energy system emphasis), game planning for different opponent styles, and video analysis of competitive footage.

6. Mobility and Recovery#

Flexibility, recovery, and injury prevention tools for maintaining movement quality and longevity (@shakti/mobility). This library treats mobility as its own training discipline with structured protocols — not simply a warm-up or cool-down add-on.

• Static and dynamic stretching: Stretching protocol library with muscle targeting, hold durations, intensity guidelines, and progression — distinguishing between static stretching (held position) and dynamic stretching (controlled movement through range).
• Joint mobility routines: CARs (Controlled Articular Rotations — moving a joint through its full available range under muscular control), PAILs (Progressive Angular Isometric Loads — generating force at end range), and RAILs (Regressive Angular Isometric Loads — pulling the joint to end range using the antagonist). These are the FRC (Functional Range Conditioning) protocols for developing usable mobility.
• Self-myofascial release (SMR): Foam rolling and lacrosse ball protocols organized by body region — techniques to reduce myofascial restrictions and improve tissue quality.
• Recovery protocols: Cold therapy (ice baths, cryotherapy), heat therapy (sauna, contrast bathing), compression, and recovery scheduling tools.
• Injury prevention: Pre-habilitation (prehab) routines targeting common injury sites (rotator cuff, ACL, lower back) and functional movement screening to identify asymmetries.
• Rehabilitation progressions: Return-to-training protocols with graduated loading, movement pattern retraining, and clearance checkpoints for common training injuries.

7. Biometric Tracking#

Health and performance biometrics from heart rate variability to body composition, with wearable device integration (@shakti/biometrics). The library models both the analysis algorithms and the integration catalog for real-world wearable devices.

Heart Rate and Recovery#

• Heart rate monitoring: Real-time heart rate tracking with zone calculation — Zone 1 (very light, recovery), Zone 2 (fat burn, aerobic base), Zone 3 (aerobic, cardio), Zone 4 (anaerobic threshold), Zone 5 (maximum, sprint) — based on user-specific max heart rate.
• HRV analysis: Heart rate variability (HRV) is the variation in time between successive heartbeats. High HRV indicates good recovery and adaptability; low HRV indicates stress or fatigue. Shakti analyzes HRV for daily recovery assessment and readiness scoring.
• Cardiac drift detection: Detect cardiovascular drift during prolonged exercise — the gradual rise in heart rate at a fixed intensity over time — for real-time intensity adjustment recommendations.
• Recovery scoring: Composite score combining HRV, sleep quality, subjective readiness, and training load to determine how recovered the user is and what intensity of training is appropriate.

Body and Performance#

• Body composition tracking: Track body composition changes with DEXA-equivalent estimates derived from circumference measurements, enabling trend monitoring without expensive scanning.
• Performance metrics: 1RM (one-rep maximum) estimates using Epley, Brzycki, and Lombardi formulas; power output tracking; VO2max estimation from submaximal tests. The 1RM is the maximum weight a person can lift for a single repetition — a fundamental strength measurement.
• Training load monitoring: Acute:Chronic Workload Ratio (ACWR) — comparing recent training load to longer-term average — with training stress balance and injury risk indicators. High ACWR (above ~1.5) is correlated with injury risk.

Device Integrations#

The device-integrations catalog describes how each wearable platform connects and what data it provides. These are descriptive configuration records, not live SDK clients — an application would use this catalog to build the actual integration.

• Apple Watch (HealthKit): Heart rate, workout sessions, activity rings, sleep data.
• Garmin (Garmin Connect): Multisport data, running dynamics (cadence, ground contact time, vertical oscillation), training status, and body battery metrics.
• Whoop: Strain score, recovery score, and detailed sleep stage data.
• Oura Ring: Sleep stages, readiness score, and activity tracking with high-resolution overnight HRV.
• Polar: Heart rate and training data via the Polar API.

8. AI Form Analysis and Motion Intelligence#

Computer vision-powered exercise form analysis with real-time feedback and post-session review (@shakti/form-analysis). The form-analysis library is discipline-agnostic — it provides the fault taxonomy and scoring framework that any discipline module can reference with its own technique criteria.

• Motion capture from camera: Pose estimation from device cameras using MediaPipe or TensorFlow.js to capture body joint positions in real time — no special equipment required.
• Form quality scoring: Per-joint angle analysis scores exercise form quality against ideal movement patterns for each specific exercise. A squat is not scored the same way as a deadlift.
• Technique-specific analysis: Bar path tracking for barbell lifts (the vertical path of the bar during a squat or deadlift should remain close to the center of mass), depth checking for squats (hip crease below parallel is the minimum powerlifting standard), elbow flare detection for bench press.
• Real-time visual feedback: Live overlays showing form corrections, joint angle measurements, and alignment guides during the exercise.
• Audio coaching cues: Voice-based real-time coaching cues generated contextually ("Drive your knees out," "Keep your chest up," "The bar is drifting forward").
• Post-session video analysis: Review recorded sessions with annotated form analysis and rep-by-rep scoring to identify patterns and track improvement over time.
• Fault taxonomy: A structured DeviationType catalog of 14 form faults (knee valgus/varus, butt wink, forward lean, bar drift, incomplete lockout, asymmetric shift, lumbar flexion/hyperextension, shoulder-impingement risk, heel rise, cervical hyperextension, elbow flare, wrist deviation), each scored by severity and rolled into a letter grade. The library is self-contained — it imports no external pose-estimation package.

9. Personalization and AI Coaching#

Adaptive training that evolves with each user based on goals, progress, recovery, and preferences (@shakti/personalization). This library models the full personalization lifecycle — from initial profile creation through ongoing adaptive adjustments and goal tracking.

• Practitioner profiling: Comprehensive profiles covering fitness level, training history, goals, injury history, schedule constraints, available equipment, and movement preferences.
• Adaptive programming: Training programs that auto-adjust based on performance trends (if progress stalls, volume or intensity changes), recovery status (if readiness is low, intensity reduces), and schedule changes (if a session is missed, the program redistributes the load).
• AI workout generation: LLM and rule-system-powered workout plan generation constrained by user profile, available equipment, available time, and current readiness.
• Recommendation engine: Suggest exercises, programs, instructors, and content based on training history, stated goals, and behavior patterns.
• Goal management: Set, track, and celebrate fitness goals (e.g., "squat bodyweight," "complete 10 pull-ups," "run 5K") with milestone markers and progress visualization.
• Readiness-based scheduling: Automatically adjust training intensity and volume based on daily readiness scores — lower-intensity training on poor recovery days, higher intensity on peak readiness days.

10. Gamification and Motivation#

Engagement systems that make training compelling through achievements, streaks, challenges, and competition (@shakti/gamification). The gamification library subscribes to domain events published by the workout logging system, so achievement checking and XP awarding add no latency to the core training flow.

• Achievement system: Unlock badges for training milestones (first training session, first 5K, 100 total sessions, reach bodyweight squat, complete a 30-day streak). Achievements are designed around genuine fitness accomplishments.
• Streak tracking: Daily and weekly training streak tracking with freeze mechanics (save a streak despite a missed day) and recovery incentives (reduced requirements after breaks to rebuild consistency).
• XP and leveling: Experience point system rewarding all forms of training activity, with leveling progression, skill trees, and specialization paths (e.g., "Yoga Practitioner," "Strength Athlete," "Martial Artist").
• Challenges: Individual and group challenges with time-limited goals, leaderboards, and completion rewards — e.g., "30-day flexibility challenge" or "team total volume challenge."
• Leaderboards: Global and friend leaderboards with anti-gaming measures (normalized by training age and equipment) and fair comparison brackets.
• Virtual rewards: Cosmetic unlocks, profile customization items, and virtual achievement items as rewards for reaching training milestones.

11. Community and Social#

Social features connecting practitioners, enabling accountability, and building training communities (@shakti/community).

• Training profiles: Public training profiles with workout history, achieved milestones, current PRs (personal records), and progress photos with privacy controls.
• Activity feed: Social feed showing training logs, achievements, PRs, and community activity from followed users — celebrating others' progress.
• Training groups: Create and manage training groups for team workouts, group challenges, shared programming, and accountability.
• Accountability partners: Match with accountability partners for check-ins, shared goals, and mutual motivation — research shows social accountability significantly improves adherence.
• Messaging: In-app messaging between users and between users and their instructors.

12. Audio and Voice#

Audio content delivery and voice-controlled hands-free training (@shakti/audio). Voice control is particularly important for strength training and martial arts where the practitioner's hands are occupied and looking at a screen is impractical.

• Audio workout content: Audio-guided workouts with instructions, timing cues, rep counting, and motivational coaching — usable while looking at a barbell or mat rather than a screen.
• Music integration: Spotify and Apple Music integration with BPM-matched playlist suggestions for workout intensity — higher BPM for high-intensity intervals, lower for recovery.
• Voice commands: Hands-free voice control for starting/stopping workouts, navigating exercises, querying timers, logging sets, and asking about the next exercise — critical for lifting when hands are occupied. Voice-recognition configurations carry a wake-word-support flag for hands-free activation. (The branded Hey Shakti wake phrase itself is defined in @shakti/sota-critical — see §19.)

13. Video Content#

Video content infrastructure for instructional libraries, follow-along workouts, and live streaming (@shakti/video).

• Video content management: Upload, transcode, and deliver video content through CDN — optimized for the low-latency playback needed during active training.
• Follow-along workouts: Pre-recorded video classes with synchronized timer and rep counting — the video pauses for rest periods, counts reps, and advances through the workout automatically.
• Live streaming: Instructor-led live classes with real-time participant interaction, live form feedback, and participation metrics.
• VOD library: On-demand video library with multi-facet filtering (duration, intensity, equipment, muscle group), ratings, and bookmarking for building personal favorites.

14. 3D Visualization and Immersive Training#

Advanced visualization and emerging immersive training modalities (@shakti/visualization). This library extends form coaching into three dimensions, and lays the foundation for AR and VR training environments.

• 3D movement visualization: 3D model visualization of ideal vs. actual movement side by side for form coaching — shows exactly how the actual movement deviates from the ideal.
• Skeleton visualization: Joint-level skeleton rendering for movement analysis, showing joint angles, force estimates, and deviation from ideal ranges.
• AR form overlay: Augmented reality overlay of form guidance on a real-world camera view — shows ideal joint positions as translucent overlays on the live camera feed.
• VR fitness integration: Virtual reality training environment support for immersive workouts where the training environment is a virtual gym, ring, or outdoor space.
• Sport-specific 3D models: Pre-built 3D demonstration models for each sport and discipline, showing ideal technique from multiple camera angles.

15. Instructor and Business Tools#

Business tools enabling instructors to build and manage their practice (@shakti/instructor-sdk).

• Instructor profile: Professional profile with credentials, specializations, teaching style, reviews, ratings, and scheduling availability.
• Client management: Manage a roster of clients with individual program assignments, progress tracking, and communication history.
• Custom program builder: Build and assign fully customized training programs to clients — selecting exercises, sets/reps/weight, progression rules, and rest periods.
• Session notes: Session notes and progress annotations visible to both instructor and client, creating a shared record of each session's observations.
• Video library: Upload and manage a library of instructional videos for client use — technique demonstrations, form corrections, and educational content.
• Revenue tracking: Track session bookings, package sales, subscription revenue, and total instructor revenue with payout management.
• Instructor SDK: Programmatic access to instructor tools for third-party integrations — build custom instructor dashboards or integrate with existing studio software (@shakti/instructor-sdk).

16. Studio and Gym Management#

Operational tools for fitness studios and gyms (@shakti/studio).

• Class scheduling: Create and manage recurring class schedules with capacity management, room assignments, and instructor assignments.
• Booking system: Member class booking with waitlists, cancellation policies, automatic reminders, and attendance tracking.
• Staff management: Manage instructor schedules, availability, substitutions, payroll calculations, and performance metrics.
• Membership management: Membership tiers, billing cycles, access control (which classes/facilities each tier can access), and renewal automation.
• Facility management: Track studio space utilization, equipment inventory, maintenance schedules, and equipment usage wear.

17. Events and Scheduling#

Event management for competitions, workshops, and special training events (@shakti/events).

• Event creation: Create competitions, workshops, retreats, seminars, and special clinics with registration, pricing tiers, and capacity.
• Registration management: Handle participant registration, waitlists, payment collection, refund policies, and registration confirmation communications.
• Event scheduling: Coordinate multi-day event schedules with session management, venue management, and speaker/instructor coordination.
• Competition management: Bracket management, weight class management (for combat sports), scoring systems, and results publication for competitive events.

18. Certifications and Credentials#

Track and verify professional qualifications for instructors and practitioners (@shakti/certifications).

• Certification registry: Database of recognized fitness and wellness certifications — yoga (RYT 200, RYT 500, E-RYT), personal training (NASM, NSCA, ACE, ACSM), martial arts instructor certifications, and others.
• Credential verification: Verify instructor certifications with issuing organizations via API or document verification workflows.
• Continuing education tracking: Track ongoing education requirements (most certifications require annual CEUs — Continuing Education Units) and renewal deadlines.
• Achievement credentials: Issue digital credentials (Open Badges) for platform-based skill achievements — e.g., completing a 200-hour yoga teacher training on Shakti.
• Shakti instructor certification: Platform's own instructor certification program with curriculum tracking, assessment, and credential issuance.

19. State-of-the-Art Critical Features#

@shakti/sota-critical contains features at the cutting edge of fitness technology — capabilities informed by competitive analysis of Tonal, Whoop, Down Dog, Zwift, and others. These are opt-in features for applications that want differentiated capabilities beyond the core platform.

• Velocity-based training (VBT): Traditional strength training prescribes load as a percentage of 1RM. VBT instead measures actual barbell velocity using an accelerometer (e.g., GymAware, PUSH band) and prescribes load based on velocity targets — automatically adjusting for daily fluctuations in strength capacity. A velocity of 0.9–1.1 m/s corresponds to roughly 60% 1RM effort regardless of daily variation.
• Readiness-gated training: Block or automatically modify workouts based on HRV and readiness scores — if readiness is below a threshold, the session automatically shifts to a lighter variant rather than forcing maximum effort when the body is not recovered.
• Genetic and biomarker personalization: Use genetic data (ACE gene, ACTN3 gene, PPARA, etc.) and biomarker data (testosterone, cortisol, ferritin, Vitamin D) to personalize training type recommendations and nutrition advice.
• Continuous glucose monitoring (CGM) integration: Real-time blood glucose data from CGM devices (Dexcom, Libre) for metabolic training optimization — understanding how different foods and training types affect blood sugar for performance and body composition.
• Biomechanics AI coaching: Real-time biomechanical assessment going beyond simple form scoring to true movement quality analysis — understanding load distribution, joint moment arms, and force transfer, not just joint angles.
• Voice-first hands-free training: Voice-controlled training built around the branded Hey Shakti wake word, with multi-language support — enabling set logging and workout control without touching the device.

The library also contains modules for dynamic sequence generation, virtual-world gamification, edge AI / offline use, smart-gym intelligence, a health AI coach, data-privacy controls, enterprise B2B, and the V2 combat-style classifier described in §21.

20. State-of-the-Art Advanced Features#

@shakti/sota-advanced contains differentiating capabilities for next-generation fitness experiences — features that require deeper research integration than the rest of the platform and are expected to evolve as sports science advances.

• Neuromuscular fatigue tracking: Track neuromuscular fatigue state through grip strength assessments, reaction time tests, or wearable neuromuscular monitors to prevent overtraining by detecting accumulated neural fatigue before it manifests as injury.
• Progressive overload AI: AI-driven progressive overload recommendations that account for all training stressors simultaneously — volume, intensity, frequency, concurrent training (cardio + lifting), life stress, sleep, and nutrition — not just one variable at a time.
• Mental health and training correlation: Correlate training patterns, training types, and intensity distributions with mood tracking and mental health outcome data — understanding which training approaches improve vs. worsen mental wellbeing for the individual.
• Sleep quality optimization: Analyze sleep data (stages, HRV during sleep, sleep timing) and provide training and lifestyle adjustments specifically to optimize sleep quality — since sleep is the primary recovery mechanism for all physical training.
• Longevity training protocols: Evidence-based training protocols oriented toward health span and longevity rather than just performance — Zone 2 cardio emphasis, strength training for lean mass preservation, mobility for joint longevity, and VO2max development for cardiovascular longevity.

21. Fighting-Game Ruleset Bridge#

A deterministic mapping layer that grounds fighting-game frame data in real combat-sport biomechanics (@shakti/fighting-ruleset-bridge, with the companion combat-style classifier in @shakti/sota-critical). Shakti's combat modules cover boxing, kickboxing, MMA, Muay Thai, wrestling, and the major martial-arts traditions as real sports; this bridge exposes that material to ruleset-bound consumers. The V2 fighting-game project (a separate monorepo) consumes the bridge through a V2-side adapter, @v2/shakti-ruleset-bridge — a documented contract, not a Shakti import.

Ruleset Profiles#

@shakti/fighting-ruleset-bridge ships seven launch ruleset profiles, one per inspirational fighting-game ruleset, identified by ShaktiRulesetId: mk (Mortal Kombat), sf (Street Fighter), tekken (Tekken), wwe (WWE 2K), ufc (UFC), sc (Soul Calibur), and dj (Def Jam: Fight for New York). Each profile is a ShaktiRulesetProfile record that maps real-sport reference numerics onto the game-feel constants the ruleset demands. The key fields are:

• Frame-data scaling: tickRate (game tick, 60 Hz default), startupScale and recoveryScale (multipliers applied to real-sport startup and recovery), and activeFrames (real, extended, or compressed).
• Reach and range: reachScale adapts real-sport reach to the ruleset's spatial model — flat 2D (SF), 3D (Tekken), or 8-way movement (SC).
• Energy systems: meterModel selects the resource gauge (super-bar, drive, heat, rage, soul-charge, fatal-blow, or blazin); staminaModel selects the fatigue model (none, ufc-cardiac, wwe-exhaustion, or dj-rush).
• Damage scaling: damageScaling carries juggle, combo, and counterHit multipliers.
• Special-rule overrides: booleans ringOut (SC only), weightDetection and pinSubmissionMiniGame (WWE/UFC only), and environmentalFinishers (MK/DJ only), plus guardImpact (parry, guard-impact, drive-impact, or none).

The transform itself is self-contained in @shakti/fighting-ruleset-bridge: transformBiomechanicsToFrameData takes a move's real-sport biomechanics input (real startup/active/recovery milliseconds, force, reach, energy and range class), applies the selected ruleset profile, and deterministically emits a ShaktiRulesetFrameDataRow; serializeShaktiFrameDataCsv writes those rows as CSV. The bridge is off the rollback path: it influences authored data, never deterministic match state.

Combat-Style Classification#

classifyV2CombatStyle (in @shakti/sota-critical) emits a per-player style classification from observed combat behavior, composing real combat-sport features with a game-context layer. It outputs a primary and secondary style (boxer, kickboxer, striker, grappler, submission-specialist), a range preference (point-blank, close, mid, far), pressureTolerance and cancelConfidence scores in 0..1, and a per-ruleset style-affinity vector for AI-director matchups. Classifications are published off-rollback as shakti.player.style.updated, emitted once per match end or per session aggregate; rollback-with-CPU consumers may use only match-start or next-match snapshots.

Per-Move Biomechanical Reference Cards#

buildShaktiMoveReferenceCard produces a Shakti reference card documenting a move's real-sport antecedent (sport, technique, energy class, range, biomechanics notes). The authoring rule is enforced in validateBiomechanicsInput: a non-game-only move is rejected unless it supplies a real sourceSport and shaktiTechnique; moves with no real antecedent — such as projectiles and finishers (Hadoken, Fatality) — must be explicitly flagged game-only. Cooking reference cards into a downstream codex corpus is documented as V2-side consumption, not Shakti-side work.

Frame-Data Output#

The bridge emits frame-data rows ready for downstream import. Each ShaktiRulesetFrameDataRow carries startup / active / recovery frames, on-hit and on-block advantage, gap-to-followup, damage, hitstop, reach in Unreal units, juggle / combo / counter-hit scaling, the profile's meter and stamina models, the special-rule flags, and the reference numerics it was derived from. serializeShaktiFrameDataCsv serializes a batch of rows to a 26-column CSV.

Planned: an opt-in player-fitness training mode that would route a player's webcam-derived movement through @shakti/form-analysis form scoring is described in the V2 integration design docs but is not yet implemented in libs/shakti/ — no such drill-validation contract exists in the current source.

22. API and Developer SDK#

The API and SDK libraries define the intended programmatic surface of the Shakti platform, so that applications and third-party integrations have a clear contract to build against (@shakti/api, @shakti/sdk).

• API configuration registry: @shakti/api models the intended API surface as data — typed configuration records for REST endpoint patterns, GraphQL schema shapes, authentication strategies, rate-limit tiers, API versions, validation formats, error handlers, documentation formats, CORS policies, and monitors — covering exercise/workout, session-tracking, social/community, instructor-business, and form-analysis endpoint groups. It is a contract/metadata library, not a running HTTP server, and binds no port.
• SDK modules: @shakti/sdk provides SDK core, resources, and utilities modules for building clients against the platform.
• Instructor SDK: @shakti/instructor-sdk adds instructor- and studio-oriented modules — assessment tools, business analytics, client management, content creation, and a program builder.
• Web modules: @shakti/web provides web portal page-specification modules (marketing/public pages, main application pages, instructor portal, studio/gym portal, video features, app foundation).
• Mobile modules: @shakti/mobile provides mobile feature-specification modules (app foundation, core screens, workout features, health-device integration, video/media, social/community, platform-specific features).
• Documentation: @shakti/documentation provides documentation-specification modules for technical, user, and exercise-content documentation.
• Testing utilities: @shakti/testing provides unit, integration, e2e, performance, and security testing utility modules.

23. Platform Infrastructure#

Deployment and platform-capability modules (@shakti/deployment).

@shakti/deployment provides five specification modules: CI/CD pipeline, containerization, GPU/ML infrastructure, infrastructure setup, and monitoring/observability. Cross-cutting capabilities such as offline mode, multi-language support, accessibility, and data-privacy controls are modelled within the relevant feature libraries — for example, edge AI / offline use, global/cultural features, accessibility/inclusion, and data-privacy controls all live in @shakti/sota-critical and @shakti/sota-advanced.

Shakti libraries are pure TypeScript knowledge bases with no runtime dependencies — they bind no network port and embed no Redis or database client. The libs/shakti/README.md lists an aspirational API port and Redis namespace; those describe an intended deployment target, not behaviour implemented in libs/shakti/.