Welcome - SergeiGolos/wod-wiki GitHub Wiki

WOD.Wiki – Developer Documentation

"Write your workout like code, run it like an app."

WOD.Wiki is a TypeScript/React toolkit for authoring, executing, and analyzing functional fitness workouts. It combines a specialized markdown-like language with a Monaco-powered editor, a reactive runtime engine, and a rich component library.

Architecture Overview

The wod.wiki system consists of several key architectural components:

flowchart TB
    Editor[Editor System] --> Parser
    Parser --> Runtime[Runtime System]
    Runtime --> UI[UI Components]
    
    subgraph Editor System
        WodWikiEditor[Monaco Editor]
        SyntaxHighlighting
        Completion
    end
    
    subgraph Parser
        Tokenizer
        SyntaxTree
        ASTBuilder
    end
    
    subgraph Runtime System
        TimerRuntime
        RuntimeBlocks
        EventSystem
        MetricsSystem
    end
    
    subgraph UI Components
        TimerDisplay
        ButtonRibbon
        ResultsDisplay
    end

Core Components

Editor

The Monaco-based editor provides a rich environment for authoring workout scripts:

Syntax highlighting for workout elements
Auto-completion for exercise names and formats
Real-time validation and error reporting

Parser/Compiler

The parser transforms text into executable structures:

Tokenization of workout notation
Construction of abstract syntax tree
Statement and fragment identification

Runtime Engine

The runtime executes workout scripts using a reactive architecture:

Event-driven execution model
Block-based component system
Metrics collection and reporting

UI Components

The UI components provide visual representation and user interaction:

Timer display with visual feedback
Control buttons for workout execution
Results display for performance metrics

Key Features

Custom Workout Notation - A domain-specific language for functional fitness
Just-In-Time Compilation - Dynamic creation of executable blocks
Reactive Event System - RxJS-based event handling
Block Strategy Pattern - Extensible execution strategies
Comprehensive Metrics - Detailed workout performance tracking
Chromecast Integration - External display functionality

Workflow Overview

A typical workflow in wod.wiki follows these steps:

User writes workout script in the editor
Script is parsed into a syntax tree
Runtime compiles the tree into executable blocks
User starts the workout via UI controls
Runtime executes blocks according to the script
Results are collected and displayed

Documentation Sections

The documentation is organized into the following sections:

Components - Details of the React components and their relationships
Core - Runtime engine, workflow, and implementation details
Chromecast - Chromecast integration functionality
Syntax - Comprehensive guide to the workout notation language

Note: This documentation is automatically synchronized to the project's GitHub Wiki whenever changes are pushed to the main branch.

Getting Started as a Developer

Prerequisites

node >= 18
npm >= 9

Installation

# Clone the repository
git clone https://github.com/your-org/wod-wiki.git

# Install dependencies
cd wod-wiki
npm install

# Run Storybook
npm run dev

Key Development Scripts

Command	Purpose
`npm run dev`	Run Storybook at `localhost:6006`
`npm run build`	Build library into `dist/`
`npm run test`	Execute Vitest suite
`npm run lint`	ESLint + Prettier (if configured)

Project Structure

src/
  components/          ← React UI & hooks
  core/                ← Parser • Runtime • Types
    runtime/           ← Runtime components
    parser/            ← Syntax parsing
  cast/                ← Chromecast functionality
  contexts/            ← React context providers
  stories/             ← Storybook demos

Extension Points

The wod.wiki system is designed for extensibility at several key points:

Block Strategies - Add new runtime block behaviors
Workout Elements - Extend the syntax with new fragment types
UI Components - Create custom visualizations
Metrics Processors - Add specialized metrics calculations
External Integrations - Connect with external services

Contributing

Contributions are welcome! Please follow these guidelines:

Fork the repository
Create a feature branch
Make your changes
Add tests for new functionality
Ensure all tests pass
Submit a pull request