# ray053/unitydancesystem architecture

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

- Interactive diagram: https://gitdiagram.com/ray053/unitydancesystem
- Repository: https://github.com/ray053/unitydancesystem

## Overview

##### Project Type and Purpose
- From the README and file tree, “UnityDanceSystem” is a full-stack, interactive dance-learning platform that fuses:
- A Nuxt 3 + Vue 3 front end (with Tailwind CSS and shadcn/vue UI components)
- Unity WebGL for 3D rendering of dance guidance
- Kinect for motion capture
- A Node.js + Express back end (API + Laban motion-analysis engine)
- Persistent storage for users, courses, and learning history

##### File-Structure Analysis
- Top-level npm project with pnpm-lock.yaml, package.json, tsconfig.json
- Frontend in root:
- nuxt.config.ts, app.vue, layouts/, pages/, components/ (shadcn/vue under components/ui), assets/, public/
- .nuxt/ is the generated Nuxt build output
- Routing defined by pages/ and router/index.ts
- Server/API code under server/ (TypeScript) – Nuxt’s server/ directory auto-exposes API endpoints via file conventions
- Shared utilities in lib/utils.ts
- Tailwind config and ESLint config for styling and linting

##### Key Architectural Components
a. Frontend Layer (Nuxt 3)
- Pages & Views (pages/)
- UI Components (components/ui)
- Layouts (layouts/AdminLayout.vue)
- Assets & Static Content (assets/, public/)
- Unity WebGL embed (likely loaded in a page via <iframe> or custom component)
b. Kinect Motion-Capture Service
- External hardware client that streams raw skeletal/motion data to the back end
c. Motion-Analysis Engine (Node.js/Express)
- Server/API (server/ folder)
- Implements Laban analysis (via HumanMotionAnalysis lib)
- Exposes REST or WebSocket endpoints for real-time feedback
d. Database Layer
- Stores users, roles, courses, progress, analysis results (could be PostgreSQL, MongoDB, etc.)

##### Relationships and Data Flows
1. User’s browser loads the Nuxt3 app.
2. Unity WebGL module is initialized inside the front end for 3D visualization.
3. Kinect device streams motion data to the Node.js back end (via WebSocket or REST).
4. Back end performs Laban analysis and persists raw data + analysis results in the DB.
5. Back end pushes analysis results back to the front end (via WebSocket or HTTP).
6. Front end updates Unity WebGL visualization in real time and updates UI components (scores, guidance).
7. Admin users access pages under /admin to manage courses, users, and view learning history via HTTP calls to the back end.

##### Architectural Patterns and Principles
- Separation of Concerns: UI vs. business logic vs. data persistence
- Modular UI: shadcn/vue component library under components/ui
- API-First: server/ auto‐exposes endpoints; front end consumes these exclusively
- Real-Time Feedback Loop: Kinect → Back end → Front end → Unity WebGL

##### Technologies & Frameworks
- Front end: Vue 3, Nuxt 3, Tailwind CSS, shadcn/vue, TypeScript
- 3D Rendering: Unity WebGL build served from public/ or assets/
- Motion Capture: Kinect SDK (external)
- Back end: Node.js, Express, TypeScript, Nuxt server middleware
- Persistence: (configure in server code; e.g., PostgreSQL/MongoDB)
- Build/Dev: pnpm, ESLint, Tailwind, Nuxt CLI

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client (Browser)" 
        direction TB
        NC["nuxt.config.ts"]:::frontend
        AV["app.vue"]:::frontend
        subgraph "UI Components"
            direction TB
            UI["components/ui/"]:::frontend
        end
        subgraph "Pages & Views"
            direction TB
            P1["pages/index.vue"]:::frontend
            P2["pages/login.vue"]:::frontend
            P3["pages/courses/1.vue"]:::frontend
            P4["pages/courses.vue"]:::frontend
            P5["pages/admin/"]:::frontend
        end
        LL["layouts/AdminLayout.vue"]:::frontend
        AS["assets/"]:::frontend
        PU["public/"]:::frontend
        UW["Unity WebGL Module"]:::frontend
    end

    %% External Device
    KD["Kinect Device"]:::realtime

    %% Server Layer
    subgraph "Server (Node.js/Express)" 
        direction TB
        SV["server/"]:::backend
        LU["lib/utils.ts"]:::backend
        RT["server/tsconfig.json"]:::backend
        RC["router/index.ts"]:::backend
    end

    %% Storage Layer
    DB[(Database)]:::storage

    %% Connections
    KD -->|"motionDataStream"| SV
    NC -->|"configures app"| AV
    AV -->|"HTTP API Calls"| SV
    SV -->|"save/read data"| DB
    SV -->|"analysisResults"| AV
    AV -->|"initialize Unity"| UW
    UW -->|"renders 3D guidance"| AV

    %% Click Events
    click NC "https://github.com/ray053/unitydancesystem/blob/main/nuxt.config.ts"
    click AV "https://github.com/ray053/unitydancesystem/blob/main/app.vue"
    click UI "https://github.com/ray053/unitydancesystem/tree/main/components/ui/"
    click P1 "https://github.com/ray053/unitydancesystem/blob/main/pages/index.vue"
    click P2 "https://github.com/ray053/unitydancesystem/blob/main/pages/login.vue"
    click P3 "https://github.com/ray053/unitydancesystem/blob/main/pages/courses/1.vue"
    click P4 "https://github.com/ray053/unitydancesystem/blob/main/pages/courses.vue"
    click P5 "https://github.com/ray053/unitydancesystem/tree/main/pages/admin/"
    click LL "https://github.com/ray053/unitydancesystem/blob/main/layouts/AdminLayout.vue"
    click AS "https://github.com/ray053/unitydancesystem/tree/main/assets/"
    click PU "https://github.com/ray053/unitydancesystem/tree/main/public/"
    click SV "https://github.com/ray053/unitydancesystem/tree/main/server/"
    click LU "https://github.com/ray053/unitydancesystem/blob/main/lib/utils.ts"
    click RT "https://github.com/ray053/unitydancesystem/blob/main/server/tsconfig.json"
    click RC "https://github.com/ray053/unitydancesystem/blob/main/router/index.ts"

    %% Styles
    classDef frontend fill:#D6EFFF,stroke:#000,stroke-width:1px
    classDef backend fill:#FFE0B2,stroke:#000,stroke-width:1px
    classDef realtime fill:#C8E6C9,stroke:#000,stroke-width:1px
    classDef storage fill:#E0E0E0,stroke:#000,stroke-width:1px
```
