# nmhp16/motion_ai architecture

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

- Interactive diagram: https://gitdiagram.com/nmhp16/motion_ai
- Repository: https://github.com/nmhp16/motion_ai

## Overview

##### Project type and purpose
- Motion AI is a hybrid desktop-plus-microservice application.
- It uses a JavaFX front end (GUI), a set of Python modules (pose estimation, real-time processing, AI calls), and a local “motion_database” of professional dance videos/key-point data.

##### File structure
- Top-level “src/main/java/com/instructor/…” contains your core Java backend:
- algorithms (DTW, sorts), data readers/processors, evaluators (scoring/feedback), controller & UI entry points.
- “motion_database” holds raw video files and annotation text.
- “pose_detection” and “real_time” are Python scripts using MediaPipe + OpenCV.
- “web_call” houses a Python module for external AI service calls (SpeechRecognition/PyAudio).
- POM.xml and module-info.java define Maven/JavaFX configuration.

##### Extract architectural insights from the README
- JavaFX UI (“DanceInstructorUI”) orchestrates the user flow.
- Python scripts perform pose estimation (real time or batch), returning keypoints maps (JSON/text).
- Core algorithms (MergeSort, DTW, Normalization, Interpolation, Moving Average) run in Java under “com.instructor.algorithms” and “com.instructor.data” → “com.instructor.evaluation.”
- Data flows from raw video → Python MediaPipe → Java processing → UI feedback.

##### Main components and their roles
A. Frontend / Presentation layer
- JavaFX GUI (DanceInstructorUI + controller)
B. Backend Java processing layer
- FileCleanup/ApplicationHandler (I/O)
- PoseDataReader/Processor → sorts, normalizes, interpolates → evaluator
- Algorithms (DTW, sorts)
- JointScoring/PoseFeedback
C. Python services
1. pose_detection/PoseDetection.py & PoseUpload.py – offline pose extraction
2. real_time/app.py – real-time pose stream (Flask or similar)
3. web_call/AI_Call.py – optional external AI/Speech service
D. Data storage
- motion_database (AVI + TXT)
- professional_keypoints.json (real_time)
E. External services & libs
- MediaPipe, OpenCV, SpeechRecognition, PyAudio

##### Relationships & data flows
1. User interacts with JavaFX UI → loads video or selects real-time mode
2. UI invokes Python pose service (batch or real time)
- Could be via subprocess calls (e.g. “python PoseDetection.py”) or HTTP API calls to real_time/app.py
3. Python returns keypoints JSON/text → UI/backend layer
4. Java processing pipeline:
a. PoseDataReader parses JSON/text
b. MergeSort/InsertionSort orders frames
c. DTW aligns user vs. pro sequences
d. Normalization (torso scaling)
e. Linear interpolation fills gaps
f. Moving average smooths data
g. JointScoring & PoseFeedback compute metrics
5. UI displays feedback, scores, and suggestions
6. Optionally, UI or backend calls AI_Call.py for voice guidance

##### Key architectural patterns & principles
- Layered architecture: Presentation → Application logic → Data processing → Data storage
- Microservices style for Python pose modules (separate processes or APIs)
- Modular algorithms (each in its own class under com.instructor.algorithms)
- File-based data store (no heavy DB) for videos/keypoints

- Major components and label them.
- Related classes under package-level containers.
- File-storage nodes for motion_database and JSON outputs.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Presentation Layer"
        direction TB
        UI["DanceInstructorUI\n(Java 23 + Maven + JavaFX)"]:::frontend
        UIController["DanceInstructorUIController"]:::frontend
        MainApp["Main"]:::frontend
    end

    %% Python Services
    subgraph "Python Services" 
        direction TB
        PoseDetect["PoseDetection.py\n(Python 3.8 + MediaPipe)"]:::python
        PoseUpload["PoseUpload.py"]:::python
        RealTimeApp["app.py\n(Flask Stream)"]:::python
        PreprocPro["preprocess_pro_video.py"]:::python
        KeypointsJSON["professional_keypoints.json"]:::datastore
        AICall["AI_Call.py\n(SpeechRecognition + PyAudio)"]:::python
    end

    %% Java Processing Layer
    subgraph "Core Java Processing"
        direction TB
        ControllerHandler["ApplicationHandler.java"]:::core
        FileCleanup["FileCleanup.java"]:::core
        PoseReader["PoseDataReader.java"]:::core
        PoseProc["PoseDataProcessing.java"]:::core
        subgraph "Algorithms"
            direction TB
            Insertion["InsertionSort.java"]:::core
            Merge["MergeSort.java"]:::core
            DTW["DynamicTimeWarping.java"]:::core
            DecisionTree["DecisionTree.java"]:::core
        end
        subgraph "Evaluation"
            direction TB
            JointScore["JointScoring.java"]:::core
            PoseScore["PoseScoring.java"]:::core
            Feedback["PoseFeedback.java"]:::core
        end
    end

    %% Data Storage
    subgraph "Data Storage"
        direction TB
        MotionDB["motion_database/"]:::datastore
        VideoTXT["AVI + TXT Files"]:::datastore
    end

    %% External Libraries/Services
    subgraph "External Libraries"
        direction TB
        MediaPipe["MediaPipe"]:::external
        OpenCV["OpenCV"]:::external
        SpeechAPI["SpeechRecognition"]:::external
        PyAudio["PyAudio"]:::external
    end

    %% Relationships & Data Flows
    UI -->|"start UI"| MainApp
    MainApp -->|"load video or real-time"| UIController
    UIController -->|"invoke batch service"| PoseDetect
    UIController -->|"invoke batch upload"| PoseUpload
    UIController -->|"HTTP stream"| RealTimeApp
    UIController -->|"invoke AI call"| AICall
    PoseDetect -->|"keypoints JSON"| PoseReader
    PoseUpload -->|"keypoints JSON"| PoseReader
    RealTimeApp -->|"stream JSON"| PoseReader
    KeypointsJSON -->|"pro keypoints"| PoseReader
    MotionDB -->|"read raw video"| ControllerHandler
    ControllerHandler --> FileCleanup
    FileCleanup --> PoseReader
    PoseReader --> PoseProc
    PoseProc --> Insertion
    PoseProc --> Merge
    Insertion --> DTW
    Merge --> DTW
    DTW --> PoseProc
    PoseProc --> JointScore
    JointScore --> PoseScore
    PoseScore --> Feedback
    Feedback --> UI
    AICall --> SpeechAPI
    AICall --> PyAudio
    PoseDetect --> MediaPipe
    PoseDetect --> OpenCV
    RealTimeApp --> MediaPipe
    RealTimeApp --> OpenCV

    %% Click Events
    click UI "https://github.com/nmhp16/motion_ai/blob/master/src/main/java/com/instructor/main/DanceInstructorUI.java"
    click UIController "https://github.com/nmhp16/motion_ai/blob/master/src/main/java/com/instructor/main/DanceInstructorUIController.java"
    click MainApp "https://github.com/nmhp16/motion_ai/blob/master/src/main/java/com/instructor/main/Main.java"
    click ControllerHandler "https://github.com/nmhp16/motion_ai/blob/master/src/main/java/com/instructor/controller/ApplicationHandler.java"
    click FileCleanup "https://github.com/nmhp16/motion_ai/blob/master/src/main/java/com/instructor/controller/FileCleanup.java"
    click PoseReader "https://github.com/nmhp16/motion_ai/blob/master/src/main/java/com/instructor/data/PoseDataReader.java"
    click PoseProc "https://github.com/nmhp16/motion_ai/blob/master/src/main/java/com/instructor/data/PoseDataProcessing.java"
    click DecisionTree "https://github.com/nmhp16/motion_ai/blob/master/src/main/java/com/instructor/algorithms/DecisionTree.java"
    click DTW "https://github.com/nmhp16/motion_ai/blob/master/src/main/java/com/instructor/algorithms/DynamicTimeWarping.java"
    click Insertion "https://github.com/nmhp16/motion_ai/blob/master/src/main/java/com/instructor/algorithms/InsertionSort.java"
    click Merge "https://github.com/nmhp16/motion_ai/blob/master/src/main/java/com/instructor/algorithms/MergeSort.java"
    click JointScore "https://github.com/nmhp16/motion_ai/blob/master/src/main/java/com/instructor/evaluation/JointScoring.java"
    click PoseScore "https://github.com/nmhp16/motion_ai/blob/master/src/main/java/com/instructor/evaluation/PoseScoring.java"
    click Feedback "https://github.com/nmhp16/motion_ai/blob/master/src/main/java/com/instructor/evaluation/PoseFeedback.java"
    click PoseDetect "https://github.com/nmhp16/motion_ai/blob/master/pose_detection/PoseDetection.py"
    click PoseUpload "https://github.com/nmhp16/motion_ai/blob/master/pose_detection/PoseUpload.py"
    click RealTimeApp "https://github.com/nmhp16/motion_ai/blob/master/real_time/app.py"
    click PreprocPro "https://github.com/nmhp16/motion_ai/blob/master/real_time/preprocess_pro_video.py"
    click KeypointsJSON "https://github.com/nmhp16/motion_ai/blob/master/real_time/professional_keypoints.json"
    click AICall "https://github.com/nmhp16/motion_ai/blob/master/web_call/AI_Call.py"

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#004085,color:#004085
    classDef core fill:#d4edda,stroke:#155724,color:#155724
    classDef python fill:#fff3cd,stroke:#856404,color:#856404
    classDef datastore fill:#e2e3e5,stroke:#6c757d,color:#6c757d
    classDef external fill:#f5c6cb,stroke:#721c24,color:#721c24
```
