# wywywang/coachai-projects architecture

> Architecture diagram of the GitHub repository wywywang/coachai-projects, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/wywywang/coachai-projects
- Repository: https://github.com/wywywang/coachai-projects

## Overview

##### Project Type and Purpose
- This is a single “monorepo” that bundles **nine** distinct badminton‐analytics sub-projects (e.g., Visualization Platform, Shot Influence, Stroke Forecasting, Strategic Environment, Movement Forecasting, CoachAI Environment, RallyNet, ShuttleSet, CoachAI-Challenge).
- Each sub-project is essentially an **ML/data-processing pipeline** or an **RL environment** plus a front-end (Visualization Platform). They run end-to-end experiments: ingest raw match data → preprocess → model training/prediction → evaluation → (optionally) visualization.

##### High-Level Components
A. Data Sources (raw CSVs, datasets)
- ShuttleSet, ShuttleSet22, RallyNet/Data, Strategic Environment/Data, Stroke Forecasting/data, CoachAI-Challenge data, etc.
B. Preprocessing Layer
- Python scripts/notebooks: badmintoncleaner.py, data_cleaner.py, prepare_dataset.py, preprocess scripts under each sub-project, Visual Platform’s preprocessing code.
C. Modeling / Training Pipelines
1. Shot Influence Module (Shot Influence/)
– cnn.py, rally_classifier.py, train.py, evaluate.py, util.py
2. Stroke Forecasting Module (Stroke Forecasting/)
– ShuttleNet, LSTM, Transformer subfolders + train.py, evaluate.py, generator.py, utils.py
3. Movement Forecasting Module (Movement Forecasting/)
– DyMF, rGCN, GCN, LSTM, Transformer code + train.py, evaluate.py, runner scripts
4. Strategic Environment & CoachAI RL Env (Strategic Environment/, CoachAI Badminton Environment/)
– multiagent core, environment, policy, Gym-style wrappers, RL algorithms (a2c.py, ppo.py, ddpg.py)
5. RallyNet Module (RallyNet/)
– data loaders, policy/models (generator, transformer), train.py, evaluate.py
D. Evaluation & Results
– evaluate.py in each module, saved_model directories (RallyNet/Results), demo.csv, metrics scripts
E. Visualization Front-End
– Visualization Platform/cgi-bin (CGI-Python scripts), HTML/CSS/JS pages, autoanalysis.html, ourdata.html, trajectory.html

##### Relationships & Data Flows
- **Preprocessing → Modeling**: cleaned datasets feed into each module’s train.py/runner.py.
- **Evaluation → Visualization** (optional): some evaluation outputs (e.g. prediction CSVs, heatmaps) are ingested by the Visualization Platform.

##### Architectural Patterns & Principles
- **Modular pipeline pattern**: clear separation between data, preprocessing, modeling, evaluation, and visualization.
- **Reusable components**: each sub-project implements its own `environment.yml` and isolated codebase but follows the same flow.
- **Layered architecture**: Data layer → Processing layer → Application (model) layer → Presentation (visualization) layer.

##### Technologies & Frameworks
- Language: Python 3.x (+ Jupyter notebooks)
- ML Frameworks: PyTorch/TensorFlow (implicit in model files), scikit-learn (for classical models in RallyNet), custom CNN/Transformer code
- RL: OpenAI Gym–style multiagent environment, stable-baseline-style algorithms (ppo.py, a2c.py, ddpg.py)
- Data/storage: CSV, NumPy (.npy), Pickle (.pkl)
- Visualization: CGI-Python backend, HTML5/CSS3/JavaScript frontend
- Environment management: Conda (`environment.yml` in each module)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Data Sources Layer
    subgraph "Data Sources"
        direction TB
        DS1["ShuttleSet"]:::datastore
        DS2["ShuttleSet22"]:::datastore
        DS3["RallyNet/Data"]:::datastore
        DS4["StrategicEnv/Data"]:::datastore
        DS5["StrokeForecasting/data"]:::datastore
        DS6["CoachAI-Challenge Data"]:::datastore
    end

    %% Preprocessing Layer
    subgraph "Preprocessing" 
        direction TB
        PP1["badmintoncleaner.py & data_cleaner.py"]:::preproc
        PP2["prepare_dataset.py & module preprocess scripts"]:::preproc
    end

    %% Modeling / Training Layer
    subgraph "Modeling / Training"
        direction TB
        subgraph "Shot Influence Module" 
            SI["Shot Influence Models & train.py"]:::model
        end
        subgraph "Stroke Forecasting Module"
            SF["ShuttleNet/LSTM/Transformer & train.py"]:::model
        end
        subgraph "Movement Forecasting Module"
            MF["DyMF/rGCN/GCN & train.py"]:::model
        end
        subgraph "Strategic & CoachAI Env"
            SE["Multiagent Core & RL Algos"]:::model
        end
        subgraph "CoachAI Badminton Environment"
            CA["Gym-style Env & Movement Submodule"]:::model
        end
        subgraph "RallyNet Module"
            RN["Data Loaders & train.py"]:::model
        end
    end

    %% Evaluation Layer
    subgraph "Evaluation & Results"
        direction TB
        EV1["evaluate.py & metrics scripts"]:::eval
        EV2["Saved Models & Results"]:::eval
    end

    %% Visualization Layer
    subgraph "Visualization Front-End"
        direction TB
        VB["User Browser"]:::ui
        CGI["CGI-Python scripts"]:::ui
        UI["HTML/CSS/JS pages"]:::ui
    end

    %% Data Flows
    DS1 --> PP1
    DS2 --> PP1
    DS3 --> PP1
    DS4 --> PP1
    DS5 --> PP1
    DS6 --> PP1

    PP1 --> PP2
    PP2 --> SI
    PP2 --> SF
    PP2 --> MF
    PP2 --> SE
    PP2 --> CA
    PP2 --> RN

    SI --> EV1
    SF --> EV1
    MF --> EV1
    SE --> EV1
    CA --> EV1
    RN --> EV1

    EV1 --> EV2
    EV2 --> CGI
    CGI --> UI
    UI --> VB

    %% RL Loop
    SE -.->|"control loop"| SE
    SE -.->|"Agent↔Environment"| SE
    CA -.->|"control loop"| CA
    CA -.->|"Agent↔Environment"| CA

    %% Click Events
    click VB "https://github.com/wywywang/coachai-projects/tree/main/Visualization Platform/"
    click SI "https://github.com/wywywang/coachai-projects/tree/main/Shot Influence/"
    click SF "https://github.com/wywywang/coachai-projects/tree/main/Stroke Forecasting/"
    click MF "https://github.com/wywywang/coachai-projects/tree/main/Movement Forecasting/"
    click SE "https://github.com/wywywang/coachai-projects/tree/main/Strategic Environment/"
    click CA "https://github.com/wywywang/coachai-projects/tree/main/CoachAI Badminton Environment/"
    click RN "https://github.com/wywywang/coachai-projects/tree/main/RallyNet/"
    click DS1 "https://github.com/wywywang/coachai-projects/tree/main/ShuttleSet/"
    click DS6 "https://github.com/wywywang/coachai-projects/tree/main/CoachAI-Challenge-IJCAI2023/"

    %% Styles
    classDef datastore fill:#cce5ff,stroke:#005cbf,stroke-width:1px;
    classDef preproc fill:#d4edda,stroke:#155724,stroke-width:1px;
    classDef model fill:#ffe5b4,stroke:#d39e00,stroke-width:1px;
    classDef eval fill:#e2e3e5,stroke:#6c757d,stroke-width:1px;
    classDef ui fill:#fff3cd,stroke:#856404,stroke-width:1px;
```
