# maxwshen/piu-annotate architecture

> Architecture diagram of the GitHub repository maxwshen/piu-annotate, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2024-12-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/maxwshen/piu-annotate
- Repository: https://github.com/maxwshen/piu-annotate

## Overview

Main Components to Include:

##### Core Processing Pipeline
- Input Layer
- Chart structure conversion (formats/ssc_to_chartstruct.py)

- Analysis Engine
- Segment Analysis (piu_annotate/segment/)
- Pattern Recognition (piu_annotate/reasoning/)
- Difficulty Assessment (piu_annotate/difficulty/)
- Limb Usage Prediction (cli/limbuse/)

- Output Formats
- JSON outputs (cli/chartjson/)
- Visualization components (formats/jsplot.py)

##### Machine Learning Infrastructure
- Feature Engineering (ml/featurizers.py)
- Model Training (ml/models.py)
- Prediction Pipeline (ml/predictor.py)
- Tactics Analysis (ml/tactics.py)

##### Data Flow Architecture
- Raw input (SSC files) → Chart Structure conversion
- Chart Structure → Various Analysis Modules
- Analysis Results → Output Formats

##### CLI Interface Layer
- CLI tools into functional categories:
- Ingestion Tools (cli/ingest/)
- Analysis Tools (cli/analysis/)
- Debug Tools (cli/debug/)
- Tools (cli/display_metadata/)

Specific Design Guidelines:

##### Technical Details
- Use of Python as the primary language
- Libraries (based on imports in the code)
- File format transformations (SSC → ChartStruct → JSON)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Define styles
    classDef input fill:#a8d1f0,stroke:#333
    classDef processing fill:#90EE90,stroke:#333
    classDef ml fill:#FFE5B4,stroke:#333
    classDef output fill:#FFA07A,stroke:#333
    classDef utility fill:#D3D3D3,stroke:#333

    %% Input Layer
    subgraph InputLayer["Input Processing"]
        SSCParser["SSC File Parser"]
        ChartConv["Chart Structure Converter"]
    end
    click SSCParser "https://github.com/maxwshen/piu-annotate/blob/main/piu_annotate/formats/sscfile.py"
    click ChartConv "https://github.com/maxwshen/piu-annotate/blob/main/piu_annotate/formats/ssc_to_chartstruct.py"

    %% Analysis Engine
    subgraph AnalysisEngine["Analysis Engine"]
        SegAnalysis["Segment Analysis"]
        PatternRec["Pattern Recognition"]
        DiffAssess["Difficulty Assessment"]
        LimbPred["Limb Usage Prediction"]
    end
    click SegAnalysis "https://github.com/maxwshen/piu-annotate/tree/main/piu_annotate/segment/"
    click PatternRec "https://github.com/maxwshen/piu-annotate/tree/main/piu_annotate/reasoning/"
    click DiffAssess "https://github.com/maxwshen/piu-annotate/tree/main/piu_annotate/difficulty/"
    click LimbPred "https://github.com/maxwshen/piu-annotate/tree/main/cli/limbuse/"

    %% ML Infrastructure
    subgraph MLInfra["Machine Learning Infrastructure"]
        FeatureEng["Feature Engineering"]
        ModelTrain["Model Training"]
        PredPipe["Prediction Pipeline"]
        TacticsAnal["Tactics Analysis"]
    end
    click FeatureEng "https://github.com/maxwshen/piu-annotate/blob/main/piu_annotate/ml/featurizers.py"
    click ModelTrain "https://github.com/maxwshen/piu-annotate/blob/main/piu_annotate/ml/models.py"
    click PredPipe "https://github.com/maxwshen/piu-annotate/blob/main/piu_annotate/ml/predictor.py"
    click TacticsAnal "https://github.com/maxwshen/piu-annotate/blob/main/piu_annotate/ml/tactics.py"

    %% CLI Interface
    subgraph CLILayer["CLI Interface"]
        Ingest["Ingestion Tools"]
        Analysis["Analysis Tools"]
        Debug["Debug Tools"]
        Display["Display Tools"]
    end
    click Ingest "https://github.com/maxwshen/piu-annotate/tree/main/cli/ingest/"
    click Analysis "https://github.com/maxwshen/piu-annotate/tree/main/cli/analysis/"
    click Debug "https://github.com/maxwshen/piu-annotate/tree/main/cli/debug/"
    click Display "https://github.com/maxwshen/piu-annotate/tree/main/cli/display_metadata/"

    %% Output Systems
    subgraph OutputSys["Output Systems"]
        JSONOut["JSON Output"]
        Visualize["Visualization Component"]
    end
    click JSONOut "https://github.com/maxwshen/piu-annotate/tree/main/cli/chartjson/"
    click Visualize "https://github.com/maxwshen/piu-annotate/blob/main/piu_annotate/formats/jsplot.py"

    %% Data Storage
    subgraph DataStore["Data Storage"]
        ChartStructs["Chart Structures"]
        ManualJSON["Manual JSON Data"]
        StepCharts["Step Charts Data"]
    end
    click ChartStructs "https://github.com/maxwshen/piu-annotate/tree/main/artifacts/chartstructs/"
    click ManualJSON "https://github.com/maxwshen/piu-annotate/tree/main/artifacts/manual-jsons/"
    click StepCharts "https://github.com/maxwshen/piu-annotate/tree/main/data/accessible-stepcharts/"

    %% Connections
    SSCParser --> ChartConv
    ChartConv --> SegAnalysis
    ChartConv --> PatternRec
    SegAnalysis --> DiffAssess
    PatternRec --> DiffAssess
    DiffAssess --> LimbPred
    
    FeatureEng --> ModelTrain
    ModelTrain --> PredPipe
    PredPipe --> TacticsAnal
    
    MLInfra --> AnalysisEngine
    
    AnalysisEngine --> JSONOut
    AnalysisEngine --> Visualize
    
    Ingest --> DataStore
    DataStore --> Analysis
    Analysis --> Debug
    Debug --> Display

    %% Styling
    class SSCParser,ChartConv input
    class SegAnalysis,PatternRec,DiffAssess,LimbPred processing
    class FeatureEng,ModelTrain,PredPipe,TacticsAnal ml
    class JSONOut,Visualize output
    class Ingest,Analysis,Debug,Display utility
    class ChartStructs,ManualJSON,StepCharts utility
```
