# Shakti — Systems Deep Dive

> The `libs/shakti/` area: 28 Nx libraries that make up **Shakti**, a
> physical-discipline and movement-intelligence platform — yoga, strength,
> martial arts, combat sports, biometrics, form analysis and the surrounding
> delivery/operations surfaces — expressed almost entirely as strongly-typed
> domain knowledge bases plus two real deterministic algorithm libraries wired
> into V2.

## What this area is

"Shakti" is the movement / physical-training domain of the monorepo. The 28
libraries under `libs/shakti/` cover the full breadth of a fitness platform:
movement disciplines (`@shakti/yoga`, `@shakti/strength`,
`@shakti/martial-arts`, `@shakti/combat-sports`, `@shakti/mobility`), the
sensing and intelligence layer (`@shakti/biometrics`, `@shakti/form-analysis`,
`@shakti/personalization`, `@shakti/sota-advanced`, `@shakti/sota-critical`),
engagement and operations (`@shakti/gamification`, `@shakti/community`,
`@shakti/events`, `@shakti/studio`, `@shakti/certifications`,
`@shakti/instructor-sdk`), and the delivery surfaces (`@shakti/api`,
`@shakti/web`, `@shakti/mobile`, `@shakti/video`, `@shakti/audio`,
`@shakti/visualization`, `@shakti/sdk`, `@shakti/deployment`, `@shakti/testing`,
`@shakti/documentation`). `@shakti/core` sits underneath as the type/auth/event
foundation.

The dominant implementation shape across the area is a **typed knowledge base
expressed as data**: a module declares strongly-typed catalogs (asanas, lifts,
form checkpoints, AI prompt templates, endpoint configs, infra configs, screen
specs, test plans), seeds them, and exposes accessor and query functions —
`getAll<X>()`, `get<X>ById()`, `get<X>By<Facet>()`, `search<X>()`,
`get<Area>Count()`, and `reset<Area>Stores()`. These are large modules
(typically 1,500–9,600 lines each) that are real and domain-specific —
`yoga/src/asanas.ts` (6,753 L) and `strength/src/compounds.ts` (9,632 L) are
genuine structured corpora, not stubs — but they are descriptive: they model the
domain as queryable typed records rather than as a running service.

Two libraries break that mold with real computational logic.
`@shakti/fighting-ruleset-bridge` is a pure transform that cooks combat-sport
biomechanics into deterministic fighting-game frame data, and
`@shakti/sota-critical` contains (alongside its 15 knowledge-base modules) a
real weighted combat-style classifier in `v2-combat-style-classifier.ts`. Both
stamp their outputs with SHA-256 via `@noble/hashes` and are the only libraries
in the area imported by code outside `libs/shakti/`.

#### How the libraries relate

Honestly: they mostly don't, at the import level. A grep for cross-`@shakti/*`
imports inside `libs/shakti/` returns nothing — no library imports another, and
even `@shakti/core` (intended as the shared `Result<T,E>` / RBAC / event
foundation) is not actually imported by its siblings today. Every `package.json`
in the area declares `dependencies: {}`; the only runtime third-party import
anywhere in the source is `@noble/hashes`, used by the two algorithm libraries.
So the area is best read as a **federation of independent typed domain corpora**
that share naming and structural conventions rather than a wired dependency
graph.

## How it fits the wider system

Two of the libraries are live integrations. `@shakti/fighting-ruleset-bridge` is
consumed by `V2/services/shakti-ruleset-bridge`, and `@shakti/sota-critical`
(its V2 style classifier) is consumed by
`V2/services/shakti-style-classification`. These are the only external consumers
in the tree — the eight `@shakti/*` import sites outside `libs/shakti/` are all
in those two V2 services. The bridge README is explicit about the boundary:
Shakti RPCs and transforms stay **outside** deterministic match simulation; V2's
rollback runtime consumes only the cooked frame-data tables the bridge emits.

The remaining 26 libraries are a standalone, strongly-typed domain corpus: real
and queryable, but not yet imported by any app or service in this repository.
They define the platform's surfaces as data (REST/GraphQL endpoint configs,
web/mobile screen specs, deployment/infra configs, test plans, documentation
content) rather than as executable runtimes — there are no `express`, `fastify`,
`react`, or `react-native` imports anywhere in the area. Treat the "used by"
edges on the two algorithm nodes as load-bearing, and the rest as a catalog
awaiting a consumer.

## Entity reference

### @shakti/core

The foundation library (`libs/shakti/core/src`). `types.ts` provides a real
`Result<T, E>` algebra (`ok`/`err`/`isOk`/`unwrap`/`mapResult`/`flatMap`/
`tryCatch`/`tryCatchAsync`) plus the platform's movement/anatomy/intensity type
system; `auth.ts` is RBAC with a concrete `ROLE_HIERARCHY` and
`isRoleAtLeast`/`compareRoles` helpers over seven roles; and `schemas.ts`,
`db-schema.ts`, and `events.ts` carry the schema, persistence-shape, and event
definitions. It is designed to be the shared base, though — per the cross-import
check above — the sibling libraries do not currently import it.

### @shakti/api

REST/GraphQL **API specification expressed as data** (`libs/shakti/api/src`):
`core-api.ts` plus per-area endpoint modules (`exercise-workout-endpoints.ts`,
`session-tracking-endpoints.ts`, `social-community-endpoints.ts`,
`instructor-business-endpoints.ts`, `form-analysis-endpoints.ts`). It models
endpoint configs, GraphQL schema definitions, auth strategies, rate-limit tiers,
CORS policies, and monitors as typed records with
`getAll*`/`get*By*`/`searchCoreApi`/`resetCoreApiStores` accessors. There is no
mounted server here — `dependencies` is empty and nothing imports
`express`/`fastify`; this is the API design catalog, not a running BFF.

### @shakti/audio

Audio and voice content (`libs/shakti/audio/src`): `audio-content.ts`,
`music-integration.ts`, and `voice-commands.ts`. Per its barrel header, a
"comprehensive library for audio content, music integration, and voice commands
for fitness and training applications." Implemented in the area's typed-catalog
style (large modules of structured records plus accessors), not as an audio
runtime.

### @shakti/biometrics

Health-sensing knowledge base (`libs/shakti/biometrics/src`): `heart-rate.ts`,
`recovery-metrics.ts`, `body-composition.ts`, `performance-metrics.ts`, and
`device-integrations.ts`. Models heart-rate, recovery, body-composition and
performance metrics plus wearable-device integration descriptors as typed data.
It describes device integrations as records; it does not open live device
connections.

### @shakti/certifications

Instructor credentialing domain (`libs/shakti/certifications/src`):
`credential-management.ts`, `continuing-education.ts`, `licensing-insurance.ts`,
and `shakti-certification-program.ts`. A typed corpus covering credential
tracking, continuing-education requirements, licensing/insurance records, and
the in-house certification program structure.

### @shakti/combat-sports

Combat-sport training catalogs (`libs/shakti/combat-sports/src`): `boxing.ts`,
`kickboxing.ts`, `muay-thai.ts`, `wrestling.ts`, and `mma-training.ts` (each
~2,200–2,600 L). Per its header, "a comprehensive library for boxing,
kickboxing, Muay Thai, wrestling, and MMA training integration." This is the
training-content side of the combat domain; the deterministic frame-data side
lives in `@shakti/fighting-ruleset-bridge`.

### @shakti/community

Social-feature knowledge base (`libs/shakti/community/src`):
`social-profiles.ts`, `social-feed.ts`, `training-groups.ts`,
`accountability-partners.ts`, and `messaging-system.ts`. Models profiles, feed,
training groups, accountability pairings, and messaging as typed records and
accessors — the social-graph domain modeled as data rather than a live messaging
backend.

### @shakti/deployment

Infrastructure and delivery configuration as data
(`libs/shakti/deployment/src`): `infrastructure-setup.ts`, `ci-cd-pipeline.ts`,
`containerization.ts`, `monitoring-observability.ts`, and
`gpu-ml-infrastructure.ts`. Declares load-balancer/auto-scaling/pipeline/infra
descriptors with `getAll*`/`get*By*`/`searchInfrastructure` accessors. It is a
typed catalog of infra/CI definitions (tagged `type:deployment`), not an
executable deployment tool — it does not invoke any cloud or CI runtime.

### @shakti/documentation

Documentation content corpus (`libs/shakti/documentation/src`):
`technical-documentation.ts`, `user-documentation.ts`, and
`exercise-content-documentation.ts` (each ~2,600 L). Stores technical, user, and
exercise-content documentation as structured typed records (tagged
`type:documentation`) rather than rendering pages.

### @shakti/events

Live-events and scheduling domain (`libs/shakti/events/src`):
`class-scheduling.ts`, `live-class-delivery.ts`, `competitions-tournaments.ts`,
`workshops-special-events.ts`, and `calendar-integration.ts`. A typed model of
class schedules, live delivery, competitions/tournaments, workshops, and
calendar integration descriptors.

### @shakti/fighting-ruleset-bridge

One of the two real-algorithm libraries, and the only one in the area with a
`README.md` (`libs/shakti/fighting-ruleset-bridge/src`). It owns seven
deterministic ruleset profiles (MK, SF, Tekken, WWE, UFC, Soul Calibur, Def Jam)
in `profiles/launch-profiles.ts` and a pure transform,
`transformBiomechanicsToFrameData`, that converts a move's biomechanics
(`realStartupMs`, `forceNewtons`, `reachMeters`, stamina/balance/cancel costs)
into fighting-game frame-data rows — scaling startup/active/recovery frames by
the ruleset profile, deriving hitstop, damage, reach, and on-hit/on-block
advantage, and serializing to CSV. Outputs are SHA-256 stamped via
`@noble/hashes`. It is consumed by `V2/services/shakti-ruleset-bridge`; per the
README, the transform stays outside deterministic match simulation, which reads
only cooked frame-data.

### @shakti/form-analysis

Motion-intelligence knowledge base (`libs/shakti/form-analysis/src`):
`motion-capture.ts`, `form-scoring.ts` (2,620 L), `technique-analysis.ts` (3,424
L), `real-time-feedback.ts`, and `video-analysis.ts`. `form-scoring.ts` defines
typed `FormCheckpoint`/`DeviationRule`/`BarPathProfile`/`ROMStandard`/
`TempoTemplate`/`RepQualityCriteria`/`FatigueIndicator` records with `getAll*`/
`get*ByCategory`/`get*BySeverity` accessors — a structured form-scoring rubric.
It is the descriptive scoring/analysis model; it does not run a pose-estimation
runtime in-process.

### @shakti/gamification

Engagement-mechanics domain (`libs/shakti/gamification/src`):
`achievement-system.ts`, `streak-system.ts`, `xp-leveling.ts`, `challenges.ts`,
`leaderboards.ts`, and `rewards-virtual-items.ts`. Models achievements, streaks,
XP/leveling curves, challenges, leaderboards, and virtual rewards as typed
catalogs.

### @shakti/instructor-sdk

Instructor-tooling domain (`libs/shakti/instructor-sdk/src`):
`program-builder.ts`, `client-management.ts`, `assessment-tools.ts`,
`content-creation.ts`, and `business-analytics.ts`. A typed model of the tools
an instructor uses — program building, client/roster management, assessments,
content authoring, and business analytics — expressed as records and accessors.

### @shakti/martial-arts

The largest discipline catalog (`libs/shakti/martial-arts/src`): `techniques.ts`
alone is 6,652 L, alongside `striking.ts`, `grappling.ts`, `mma.ts`,
`traditional.ts`, `weapons.ts`, `ranks.ts`, and `sparring.ts`. Per its header, a
"comprehensive martial arts module" spanning techniques, striking, grappling,
MMA, traditional arts, weapons, ranking systems, and sparring/competition — a
deep typed corpus of martial-arts knowledge.

### @shakti/mobile

Mobile-app **specification as data** (`libs/shakti/mobile/src`):
`app-foundation.ts`, `core-screens.ts`, `workout-features.ts`,
`video-media-features.ts`, `social-community.ts`,
`health-device-integration.ts`, and `platform-specific-features.ts`. Describes
the mobile app's foundation, screens, and feature set as typed records (tagged
`type:mobile`). There is no `react-native` import — this is the mobile design
catalog, not a built app.

### @shakti/mobility

Recovery and mobility domain (`libs/shakti/mobility/src`): `stretching.ts`
(2,749 L), `joint-mobility.ts`, `smr.ts` (self-myofascial release),
`recovery.ts`, `injury-prevention.ts`, and `rehabilitation.ts`. Per its header,
"a comprehensive library for stretching, joint mobility, foam rolling, recovery
protocols, injury prevention, and rehabilitation support," modeled as typed
protocol records.

### @shakti/personalization

The personalization engine domain (`libs/shakti/personalization/src`):
`practitioner-profiling.ts` (2,532 L), `adaptive-programming.ts`,
`ai-workout-generation.ts`, `recommendation-engine.ts`, and
`goal-management.ts`. `ai-workout-generation.ts` declares typed AI-integration
configs, prompt templates, constraint rules, workout templates, variety
strategies, and muscle-balance/time-constraint configs with `getAll*`/`get*ById`
accessors — i.e. it models the _configuration and prompt scaffolding_ for AI
workout generation as data; the LLM call itself is not made in-library.

### @shakti/sdk

Public-SDK surface (`libs/shakti/sdk/src`): `sdk-core.ts`, `sdk-resources.ts`,
and `sdk-utilities.ts`. A typed model of the SDK's core, resource definitions,
and utility surface for third-party integrators.

### @shakti/sota-advanced

The larger "state-of-the-art" knowledge base (`libs/shakti/sota-advanced/src`,
11 modules): `ai-coach-personal-trainer.ts`, `advanced-motion-analysis.ts`,
`wearable-deep-integration.ts`, `predictive-analytics.ts`,
`social-competitive-features.ts`, `accessibility-inclusion.ts`,
`nutrition-holistic-health.ts`, `advanced-equipment-integration.ts`,
`research-science-integration.ts`, and `global-cultural-features.ts`. Models
advanced/SOTA feature areas as typed catalogs (tagged `type:sota`). It is the
descriptive feature corpus; unlike `@shakti/sota-critical` it carries no V2
algorithm module and has no external consumer in the tree.

### @shakti/sota-critical

The second real-algorithm library (`libs/shakti/sota-critical/src`, 16 modules).
Fifteen are research-driven knowledge-base modules (`mental-health-mood.ts`,
`readiness-scheduling.ts`, `velocity-based-training.ts`,
`dynamic-sequence-generation.ts`, `vr-fitness.ts`, `genetic-biomarker.ts`,
`edge-ai-offline.ts`, `enterprise-b2b.ts`, etc., benchmarked in the header
against Tonal 2 / Whoop 5.0 / Down Dog / Zwift / Oura). The sixteenth,
`v2-combat-style-classifier.ts` (643 L), is a real algorithm:
`classifyV2CombatStyle` ingests combat telemetry events, accumulates token-match
and structured-signal weights into a per-style score vector, normalizes it, and
emits a ranked primary/secondary style with a computed confidence and
range/pressure metrics — hash-stamped via `@noble/hashes`. That classifier is
consumed by `V2/services/shakti-style-classification`.

### @shakti/strength

The strength-and-conditioning corpus and the area's largest by volume
(`libs/shakti/strength/src`): `compounds.ts` (9,632 L), `olympic.ts` (4,596 L),
`exercises.ts` (4,853 L), `calisthenics.ts` (4,027 L), `programs.ts` (3,393 L),
`powerlifting.ts`, and `hypertrophy.ts`. `compounds.ts` exposes typed
`CompoundVariation` records with `getVariationsBy*` accessors plus helpers like
`getTechniqueBreakdown`, `getMobilityPrerequisites`, `recommendProgressions`,
and `formatCompoundForDisplay` — a genuinely deep exercise-science knowledge
base.

### @shakti/studio

Studio/gym operations domain (`libs/shakti/studio/src`):
`facility-management.ts`, `equipment-management.ts`, `class-management.ts`,
`membership-management.ts`, and `staff-management.ts`. Models the back-office of
a physical studio — facilities, equipment, classes, memberships, staff — as
typed records and accessors.

### @shakti/testing

Test-plan specification as data (`libs/shakti/testing/src`): `unit-testing.ts`,
`integration-testing.ts`, `e2e-testing.ts`, `performance-testing.ts`, and
`security-testing.ts`. Declares testing strategies/plans/cases across the test
pyramid as typed records (tagged `type:testing`). It is a catalog describing
testing, not an executable test harness.

### @shakti/video

Video/media-content domain (`libs/shakti/video/src`):
`video-content-management.ts`, `instructional-video-library.ts` (2,887 L),
`follow-along-workouts.ts`, and `live-streaming.ts`. Per its header, "a
comprehensive library for video content management, instructional video library,
follow-along workouts, and live streaming infrastructure," modeled as typed
content/config records rather than a streaming runtime.

### @shakti/visualization

3D/VR/AR knowledge base (`libs/shakti/visualization/src`): `avatar-system.ts`,
`anatomy-visualization.ts`, `movement-visualization.ts`, `virtual-reality.ts`,
and `augmented-reality.ts`. Per its header, a library for "3D avatar systems,
anatomy visualization, movement visualization, virtual reality training, and
augmented reality," expressed as typed descriptors — no rendering engine is
imported.

### @shakti/web

Web-app **specification as data** (`libs/shakti/web/src`):
`web-app-foundation.ts`, `main-application-pages.ts`, `instructor-portal.ts`,
`studio-gym-portal.ts`, `video-features.ts`, and `marketing-public-pages.ts`.
Declares page/portal/search-config specs with `getAll*`/`get*By*`/
`searchMainApplicationPages`/`resetMainApplicationPageStores` accessors (tagged
`type:web`). No `react` import — this is the web information-architecture
catalog, not a built front-end.

### @shakti/yoga

The yoga discipline corpus (`libs/shakti/yoga/src`): `sequences.ts` (9,114 L),
`asanas.ts` (6,753 L), `meditation.ts`, `ayurveda.ts`, `pranayama.ts`, and
`styles.ts`. `asanas.ts` defines a typed `Asana` record (benefits,
contraindications, modifications, muscle engagement, hold duration) with rich
accessors — `getAsanasByChakra`, `getAsanasByDosha`, `getAsanasByProp`,
`getAsanasForContraindication`, `getAsanaTransitions`, `searchAsanas` — making
it a deep, queryable yoga knowledge base spanning asanas, pranayama, sequences,
styles, meditation, and Ayurveda.