# @shakti - Physical Discipline & Movement Intelligence Platform

Shakti is Oshun's comprehensive platform for movement arts, physical training,
and body intelligence. It encompasses yoga, martial arts, fitness, combat
sports, and holistic physical development with expert-level programming, form
analysis, and progression tracking.

## Overview

| Aspect              | Description                    |
| ------------------- | ------------------------------ |
| **Domain**          | Physical Discipline & Movement |
| **Scope Tag**       | `scope:shakti`                 |
| **API Port**        | 4007                           |
| **Database Schema** | `shakti`                       |
| **Namespace**       | `@shakti/*`                    |

## Capabilities

- **Yoga System**: 500+ asanas across 10+ styles (Hatha, Vinyasa, Ashtanga,
  Iyengar, Yin, Kundalini), pranayama breathing techniques, sequence building,
  and meditation integration
- **Martial Arts**: Striking (boxing, Muay Thai, karate), grappling (BJJ,
  wrestling, judo), weapons (kendo, HEMA, escrima), kata/forms libraries, belt
  progression
- **Strength Training**: Exercise database with 5000+ movements, periodization
  models (linear, undulating, block, conjugate), program generation, personal
  records
- **Combat Sports**: MMA, boxing, kickboxing round-based training, fight camp
  planning, weight management, competition preparation
- **Form Analysis**: Video-based movement analysis, joint angle detection,
  technique scoring, real-time correction feedback
- **Biometrics Integration**: Heart rate, HRV, sleep quality, readiness scores,
  wearable device sync
- **Gamification**: Achievements, streaks, challenges, leaderboards, belt/rank
  progression
- **Personalization**: AI-driven workout generation, adaptive difficulty,
  injury-aware modifications, schedule optimization

## Libraries

```
libs/shakti/
├── core/                # Foundation types, enums, schemas, events
├── yoga/                # Yoga asanas, pranayama, sequences, styles
├── martial-arts/        # Striking, grappling, weapons, kata/forms
├── strength/            # Exercise database, programs, periodization
├── combat-sports/       # MMA, boxing, fight camps, competition prep
├── mobility/            # Flexibility, ROM, recovery, prehabilitation
├── form-analysis/       # Video analysis, joint tracking, technique scoring
├── biometrics/          # Wearable sync, HRV, readiness, recovery
├── personalization/     # AI workout generation, adaptive programming
├── gamification/        # Achievements, streaks, challenges, ranks
├── community/           # Social features, groups, instructor profiles
├── certifications/      # Instructor credentials, belt ranks, skill trees
├── audio/               # Guided audio, cues, breathing timers
├── video/               # Video streaming, recording, overlay analysis
├── visualization/       # Movement graphs, progress charts, body maps
├── instructor-sdk/      # Tools for instructors to create content
├── sdk/                 # Client SDK for consuming shakti services
├── api/                 # REST/GraphQL API server
├── web/                 # Web application frontend
├── mobile/              # Mobile application
├── studio/              # Instructor studio portal
├── testing/             # Test utilities and fixtures
├── documentation/       # API docs and guides
├── deployment/          # CI/CD and deployment configs
├── sota-critical/       # Critical-path performance modules
└── sota-advanced/       # Advanced algorithms (ML-based form analysis)
```

## Quick Start

### Using the Client SDK

```typescript
import { createShaktiClient } from '@shakti/sdk';

const shakti = createShaktiClient({
  baseUrl: process.env.SHAKTI_API_URL || 'http://localhost:4007',
});

// Create a practitioner profile
const profile = await shakti.practitioners.create({
  displayName: 'Alex Chen',
  disciplines: ['yoga', 'strength_training', 'bjj'],
  fitnessLevel: 'intermediate',
  goals: ['flexibility', 'strength', 'stress_relief'],
});

// Generate a personalized workout
const workout = await shakti.workouts.generate({
  practitionerId: profile.id,
  discipline: 'strength_training',
  duration: 60, // minutes
  focus: ['upper_body', 'core'],
  equipment: ['barbell', 'dumbbells', 'pull_up_bar'],
  goal: 'hypertrophy',
});

// Start a training session
const session = await shakti.sessions.start({
  practitionerId: profile.id,
  workoutId: workout.id,
});

// Log a completed set
await shakti.sessions.logSet(session.id, {
  exerciseId: 'barbell_bench_press',
  weight: 80, // kg
  reps: 8,
  rpe: 7.5,
  tempo: { eccentric: 3, pause: 1, concentric: 1, pause: 0 },
});
```

### Yoga Session

```typescript
import { createYogaSession } from '@shakti/yoga';

// Generate a Vinyasa flow
const flow = await shakti.yoga.generateSequence({
  style: 'vinyasa',
  duration: 60,
  level: 'intermediate',
  focus: ['hip_openers', 'backbends'],
  includesPranayama: true,
  includesSavasana: true,
});

// Start guided practice
const yogaSession = await shakti.yoga.startPractice({
  practitionerId: profile.id,
  sequenceId: flow.id,
  audioGuidance: true,
});
```

### Martial Arts Training

```typescript
// BJJ technique drilling
const drill = await shakti.martialArts.createDrill({
  style: 'brazilian_jiu_jitsu',
  position: 'closed_guard',
  techniques: ['armbar', 'triangle', 'omoplata'],
  rounds: 5,
  roundDuration: 300, // seconds
  restDuration: 60,
});

// Track belt progression
const rank = await shakti.certifications.getRank({
  practitionerId: profile.id,
  discipline: 'brazilian_jiu_jitsu',
});
// => { belt: 'blue', stripes: 2, timeAtRank: '14 months' }
```

## Core Types

```typescript
import type {
  MovementPattern, // push, pull, hinge, squat, lunge, rotate, gait, carry
  BodyRegion, // upper_body, lower_body, core, full_body
  MuscleGroup, // 60+ individual muscles with anatomical precision
  JointType, // shoulder, elbow, wrist, hip, knee, ankle, spine...
  DifficultyScale, // beginner, intermediate, advanced, elite, master
  IntensityLevel, // low, moderate, high, very_high, maximal
  EnergySystem, // phosphagen, glycolytic, oxidative
  TrainingGoal, // strength, hypertrophy, endurance, power, flexibility, skill
  Laterality, // unilateral, bilateral, alternating
  PlaneOfMotion, // sagittal, frontal, transverse, multiplanar
  Tempo, // { eccentric, pause, concentric, pause }
  RepRange, // { min, max, target }
  SetConfiguration, // straight, drop, super, giant, cluster
  RestPeriod, // { duration, type: 'active' | 'passive' }
  EquipmentType, // 500+ equipment items
  ProgressionModel, // linear, undulating, block, conjugate
} from '@shakti/core';
```

## Domain Events

Shakti publishes domain events for cross-domain integration:

| Event                      | Description                             |
| -------------------------- | --------------------------------------- |
| `session.started`          | Training session began                  |
| `session.completed`        | Training session finished with metrics  |
| `exercise.performed`       | Exercise set completed with data        |
| `personal_record.achieved` | New PR set for an exercise              |
| `technique.attempted`      | Movement technique attempted with score |
| `form.analyzed`            | Video form analysis completed           |
| `program.enrolled`         | User enrolled in training program       |
| `program.completed`        | User finished a program                 |
| `achievement.unlocked`     | Gamification achievement earned         |
| `streak.milestone`         | Consistency streak milestone reached    |
| `belt.promoted`            | Martial arts belt promotion             |
| `certification.earned`     | Instructor certification achieved       |
| `injury.reported`          | Injury reported for modifications       |
| `recovery.updated`         | Recovery/readiness status changed       |
| `biometric.synced`         | Wearable device data synchronized       |

## Architecture

```
                    +------------------+
                    |   Shakti API     |
                    |   (port 4007)    |
                    +--------+---------+
                             |
              +--------------+--------------+
              |              |              |
     +--------v---+  +------v------+ +-----v-------+
     |    Yoga    |  |  Strength   | | Martial Arts|
     |   Module   |  |   Module    | |   Module    |
     +--------+---+  +------+------+ +-----+-------+
              |              |              |
              +--------------+--------------+
                             |
                    +--------v---------+
                    |  @shakti/core    |
                    |  Types, Events,  |
                    |  Schemas, Auth   |
                    +--------+---------+
                             |
              +--------------+--------------+
              |              |              |
     +--------v---+  +------v------+ +-----v-------+
     | PostgreSQL |  |    Redis    | |    MinIO    |
     |  (shakti)  |  |  (caching)  | | (media/vid) |
     +------------+  +-------------+ +-------------+
```

## Development

```bash
# Install dependencies
pnpm install

# Run core tests
pnpm nx test @shakti/core

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

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

# Lint
pnpm nx run-many --target=lint --projects=tag:scope:shakti
```

## Environment Variables

```bash
# Database
SHAKTI_DATABASE_URL=postgresql://oshun:oshun_dev@localhost:5432/shakti

# Redis (shared, namespaced)
REDIS_URL=redis://localhost:6379
SHAKTI_REDIS_PREFIX=shakti:

# Object Storage (video, images)
S3_ENDPOINT=http://localhost:9000
S3_ACCESS_KEY=minioadmin
S3_SECRET_KEY=minioadmin
SHAKTI_S3_BUCKET=shakti-media

# API
SHAKTI_API_PORT=4007
SHAKTI_API_HOST=0.0.0.0
```
