# Shakti Domain

> **Shakti** - Physical Discipline and Movement Intelligence

Library-only domain providing a comprehensive fitness, wellness, and movement
intelligence platform covering yoga, strength training, martial arts, combat
sports, biometric tracking, AI-powered form analysis, gamification, instructor
tools, and studio management. Named after the Hindu concept of primordial cosmic
energy.

---

## Overview

The Shakti domain implements a full-stack fitness technology platform that spans
from exercise science databases and movement analysis through to mobile
applications, web interfaces, and instructor business tools. The platform covers
multiple training disciplines (yoga, strength, martial arts, combat sports,
mobility) and integrates cutting-edge features including computer vision form
analysis, velocity-based training, VR fitness, genetic/biomarker
personalization, and AI coaching. Research-driven SOTA analysis against Tonal,
Whoop, Down Dog, Zwift, and others informed the feature set.

---

## Architecture

```
                    @shakti/web     @shakti/mobile
                    (web app)       (React Native)
                         |              |
                    @shakti/api
                    (REST endpoints)
                         |
    +--------+-----------+-----------+--------+--------+
    |        |           |           |        |        |
  yoga    strength   martial-arts  combat  mobility  form-
    |        |           |         sports    |      analysis
    +--------+-----------+-----------+--------+--------+
                                     |
           +-------------------------+-------------------------+
           |              |          |           |             |
    biometrics  personalization  gamification  community   events
           |              |          |           |             |
           +-------------------------+-------------------------+
                                     |
                              @shakti/core
                     (types, schemas, DB, events, auth)
```

### Layer Summary

1. **Core** - Domain types, Zod validation schemas, Drizzle ORM database schema,
   domain events, and authentication
2. **Disciplines** - Yoga, strength, martial arts, combat sports, mobility with
   exercise databases, technique libraries, and programming logic
3. **Intelligence** - Biometrics, form analysis, personalization, gamification
4. **Platform** - API endpoints, web app, mobile app, SDKs
5. **Infrastructure** - Events, testing, deployment, documentation
6. **SOTA** - State-of-the-art critical and advanced features

---

## Libraries (27)

### `@shakti/core` - Core Foundation

Core foundation providing types, Zod validation schemas, Drizzle ORM database
schema design, domain event definitions, and authentication utilities for the
entire Shakti platform.

**Key exports:** `types`, `schemas`, `db-schema`, `events`, `auth`

### `@shakti/yoga` - Yoga Instruction

Comprehensive yoga system:

- **asanas** - Complete asana database with Sanskrit names, alignment cues,
  contraindications, and difficulty ratings
- **pranayama** - Breathing technique library with timing patterns and
  physiological effects
- **sequences** - Sequence builder with intelligent pose ordering and transition
  logic
- **styles** - Yoga style definitions (Vinyasa, Ashtanga, Yin, Restorative,
  Kundalini, Bikram)
- **meditation** - Guided meditation frameworks integrated with yoga practice
- **ayurveda** - Ayurvedic constitution (dosha) assessment and practice
  recommendations

### `@shakti/strength` - Strength Training

Exercise science and strength programming:

- **exercises** - Exercise database with muscle group targeting, equipment
  requirements, and form descriptions
- **compounds** - Compound lift mechanics (squat, deadlift, bench, overhead
  press)
- **olympic** - Olympic weightlifting technique library (snatch, clean and jerk,
  progressions)
- **powerlifting** - Powerlifting meet preparation, attempt selection, and
  competition rules
- **calisthenics** - Bodyweight exercise progressions and skill trees
- **programs** - Training program templates (5/3/1, Starting Strength, GZCL,
  PPL, Upper/Lower)
- **hypertrophy** - Hypertrophy-specific training volume, intensity, and
  frequency optimization

### `@shakti/martial-arts` - Martial Arts

Comprehensive martial arts technique library:

- **techniques** - Technique database with video references and difficulty
  progression
- **striking** - Striking mechanics (punches, kicks, elbows, knees) with
  biomechanical analysis
- **grappling** - Grappling positions, submissions, escapes, and transitions
- **mma** - Mixed martial arts combining striking and grappling
- **traditional** - Traditional martial arts forms (kata, poomsae, taolu)
- **weapons** - Weapons training (bo staff, nunchaku, sword forms)
- **ranks** - Belt/rank progression tracking and grading criteria
- **sparring** - Sparring management with rules, scoring, and matchmaking

### `@shakti/combat-sports` - Combat Sports Training

Sport-specific combat training:

- **boxing** - Boxing-specific training (bag work, mitt work, footwork drills)
- **kickboxing** - Kickboxing technique and conditioning
- **muay-thai** - Muay Thai clinch work, elbow/knee techniques
- **wrestling** - Wrestling takedowns, pins, and scramble training
- **mma-training** - MMA-specific conditioning and fight preparation

### `@shakti/mobility` - Mobility and Recovery

Flexibility, recovery, and injury prevention:

- **stretching** - Static and dynamic stretching protocols with muscle targeting
- **joint-mobility** - Joint-specific mobility routines (CARs, PAILs/RAILs)
- **smr** - Self-myofascial release (foam rolling, lacrosse ball) protocols
- **recovery** - Recovery protocol management (cold/heat therapy, compression)
- **injury-prevention** - Pre-hab routines and movement screen assessments
- **rehabilitation** - Return-to-training rehabilitation progressions

### `@shakti/biometrics` - Biometric Tracking

Health and performance biometrics:

- **heart-rate** - Heart rate monitoring with zone calculation, HRV analysis,
  and cardiac drift detection
- **recovery-metrics** - Recovery scoring using HRV, sleep quality, and
  subjective readiness
- **body-composition** - Body composition tracking (DEXA-equivalent estimates,
  circumference measurements)
- **performance-metrics** - Performance metric tracking (1RM estimates, power
  output, VO2max estimation)
- **device-integrations** - Device integrations (Apple Watch, Garmin, Whoop,
  Oura, Polar)

### `@shakti/form-analysis` - Exercise Form Analysis

Computer vision and motion intelligence:

- **motion-capture** - Pose estimation from device cameras using ML models
- **form-scoring** - Form quality scoring with per-joint angle analysis
- **technique-analysis** - Technique-specific analysis (bar path tracking, depth
  checking)
- **real-time-feedback** - Real-time visual and audio feedback during exercise
- **video-analysis** - Post-session video analysis with annotation and
  comparison

### `@shakti/personalization` - User Personalization

AI-driven personalization engine:

- **practitioner-profiling** - User profiling (fitness level, goals, injuries,
  preferences, schedule)
- **adaptive-programming** - Auto-adjusting training programs based on progress
  and recovery
- **ai-workout-generation** - AI-generated workout plans using LLM and rule
  systems
- **recommendation-engine** - Content and exercise recommendation engine
- **goal-management** - Goal setting, tracking, and milestone management

### `@shakti/gamification` - Gamification and Challenges

Engagement and motivation systems:

- **achievement-system** - Achievement and badge system with unlock criteria
- **streak-system** - Training streak tracking with freeze and recovery
  mechanics
- **xp-leveling** - Experience point system with leveling and skill trees
- **challenges** - Individual and group challenges with leaderboards
- **leaderboards** - Global and friend leaderboards with anti-gaming measures
- **rewards-virtual-items** - Virtual reward items and cosmetic unlocks

### `@shakti/community` - Community Features

Social and community platform:

- **social-profiles** - Public training profiles with privacy controls
- **social-feed** - Activity feed with training log sharing
- **training-groups** - Training group creation and management
- **accountability-partners** - Accountability partner matching and check-ins
- **messaging-system** - In-app messaging between users and instructors

### `@shakti/audio` - Audio and Voice

Audio content and voice interfaces:

- **audio-content** - Audio workout content management and playback
- **music-integration** - Music service integration (Spotify, Apple Music) with
  BPM matching
- **voice-commands** - Voice command recognition for hands-free workout control

### `@shakti/video` - Video Content

Video content infrastructure:

- **video-content-management** - Video upload, transcoding, and CDN delivery
- **instructional-video-library** - Categorized instructional video library
- **follow-along-workouts** - Follow-along workout player with timer sync
- **live-streaming** - Live class streaming infrastructure

### `@shakti/visualization` - 3D Visualization and VR/AR

Visual and immersive training:

- **avatar-system** - 3D avatar system with customizable body proportions
- **anatomy-visualization** - 3D anatomy overlay showing muscle activation
- **movement-visualization** - Movement trajectory and range of motion
  visualization
- **virtual-reality** - VR training environments (Quest, Apple Vision Pro)
- **augmented-reality** - AR overlay for real-world exercise guidance

### `@shakti/api` - REST API

API endpoint definitions:

- **core-api** - Core API setup, middleware, authentication
- **exercise-workout-endpoints** - Exercise and workout CRUD endpoints
- **session-tracking-endpoints** - Training session recording endpoints
- **social-community-endpoints** - Social and community feature endpoints
- **instructor-business-endpoints** - Instructor and business management
  endpoints
- **form-analysis-endpoints** - Form analysis upload and results endpoints

### `@shakti/web` - Web Application

Web application module definitions:

- **web-app-foundation** - Next.js application foundation and routing
- **main-application-pages** - Core application pages (dashboard, workouts,
  progress)
- **instructor-portal** - Instructor dashboard and client management
- **studio-gym-portal** - Studio/gym owner management portal
- **video-features** - Video player and content features
- **marketing-public-pages** - Marketing and public-facing pages

### `@shakti/mobile` - Mobile Application

React Native mobile application:

- **app-foundation** - React Native app foundation and navigation
- **core-screens** - Core screens (home, workouts, profile)
- **workout-features** - Workout tracking and timer features
- **video-media-features** - Video playback and offline content
- **social-community** - Social features and messaging
- **health-device-integration** - HealthKit/Google Fit integration
- **platform-specific-features** - iOS and Android specific features

### `@shakti/sdk` - Developer SDK

External developer SDK:

- **sdk-core** - Core SDK client with authentication and request handling
- **sdk-resources** - Resource-specific API wrappers (exercises, workouts,
  users)
- **sdk-utilities** - SDK utility functions and helpers

### `@shakti/instructor-sdk` - Instructor Tools

Instructor-specific tooling:

- **program-builder** - Drag-and-drop program building interface
- **client-management** - Client roster, progress tracking, and communication
- **assessment-tools** - Client assessment and movement screening tools
- **content-creation** - Instructor content creation and publishing
- **business-analytics** - Revenue, retention, and engagement analytics

### `@shakti/certifications` - Instructor Certifications

Certification and credentialing:

- **credential-management** - Certification credential verification and storage
- **continuing-education** - Continuing education tracking and requirements
- **licensing-insurance** - Licensing and insurance compliance tracking
- **shakti-certification-program** - Shakti platform certification program

### `@shakti/studio` - Studio Management

Gym and studio operations:

- **facility-management** - Facility booking, room management, and scheduling
- **equipment-management** - Equipment inventory, maintenance, and utilization
- **class-management** - Class scheduling, capacity management, and waitlists
- **membership-management** - Membership plans, billing, and access control
- **staff-management** - Staff scheduling, payroll integration, and permissions

### `@shakti/events` - Event Management

Live events and scheduling:

- **class-scheduling** - Class and session scheduling with recurrence
- **live-class-delivery** - Live class delivery infrastructure
- **competitions-tournaments** - Competition and tournament management
- **workshops-special-events** - Workshop and special event organization
- **calendar-integration** - Google/Apple/Outlook calendar sync

### `@shakti/sota-critical` - SOTA Critical Features

Research-driven critical features based on competitive analysis against Tonal,
Whoop, Down Dog, Zwift, Supernatural VR, Fitbod, PUSH, and Oura:

- **mental-health-mood** - Mental health and mood tracking integration
- **readiness-scheduling** - Readiness-based training scheduling
- **velocity-based-training** - Velocity-based training with bar speed tracking
- **dynamic-sequence-generation** - AI-powered dynamic sequence generation
- **virtual-world-gamification** - Zwift-style virtual world gamification
- **longevity-healthspan** - Longevity and healthspan optimization protocols
- **genetic-biomarker** - Genetic and biomarker-informed training
- **vr-fitness** - VR fitness experiences
- **smart-gym-intelligence** - Smart gym equipment intelligence integration
- **health-ai-coach** - AI health coaching with proactive recommendations
- **advanced-social-live** - Advanced social and live training features
- **edge-ai-offline** - Edge AI for offline form analysis
- **voice-first-handsfree** - Voice-first hands-free interface
- **data-privacy-control** - User data privacy and export controls
- **enterprise-b2b** - Enterprise and B2B platform features

### `@shakti/sota-advanced` - SOTA Advanced Features

Additional advanced features:

- **ai-coach-personal-trainer** - AI coaching personal trainer
- **advanced-motion-analysis** - Advanced biomechanical motion analysis
- **wearable-deep-integration** - Deep wearable device integration
- **predictive-analytics** - Predictive performance and injury analytics
- **social-competitive-features** - Advanced social competitive features
- **accessibility-inclusion** - Accessibility and inclusion features
- **nutrition-holistic-health** - Nutrition and holistic health integration
- **advanced-equipment-integration** - Smart equipment integration
- **research-science-integration** - Exercise science research integration
- **global-cultural-features** - Global and cultural adaptation features

### `@shakti/testing` - Testing Utilities

Testing infrastructure:

- **unit-testing** - Unit test utilities and fixtures
- **integration-testing** - Integration test helpers
- **e2e-testing** - End-to-end test configuration
- **performance-testing** - Performance and load testing
- **security-testing** - Security testing tools

### `@shakti/deployment` - Deployment

Deployment configuration:

- **infrastructure-setup** - Infrastructure provisioning configuration
- **ci-cd-pipeline** - CI/CD pipeline definitions
- **containerization** - Docker containerization configuration
- **monitoring-observability** - Monitoring and observability setup
- **gpu-ml-infrastructure** - GPU/ML infrastructure for form analysis models

### `@shakti/documentation` - Documentation

Platform documentation:

- **technical-documentation** - Technical API and architecture documentation
- **user-documentation** - User-facing help and tutorial content
- **exercise-content-documentation** - Exercise content creation guidelines

---

## Technology Stack

| Component  | Technology                       |
| ---------- | -------------------------------- |
| Language   | TypeScript (ESM)                 |
| Runtime    | Node.js                          |
| Build      | Nx with `@nx/js:tsc`             |
| Testing    | Vitest                           |
| Database   | Drizzle ORM (via `@shakti/core`) |
| Validation | Zod schemas                      |
| Mobile     | React Native                     |
| Web        | Next.js                          |
| ML/CV      | TensorFlow.js, MediaPipe         |

---

## Development

```bash
# Test a specific library
pnpm nx test @shakti/core

# Build all Shakti libraries
pnpm nx run-many --target=build --projects=tag:scope:shakti

# Lint a library
pnpm nx lint @shakti/yoga

# Run all domain tests
pnpm nx run-many --target=test --projects=tag:scope:shakti
```

### Configuration

- **Project tags:** `["scope:shakti", "layer:domain", "type:lib"]`
- **Build executor:** `@nx/js:tsc`
- All libraries use ESM (`"type": "module"`)
