# steve-xmh/applemusic-like-lyrics architecture

> Architecture diagram of the GitHub repository steve-xmh/applemusic-like-lyrics, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/steve-xmh/applemusic-like-lyrics
- Repository: https://github.com/steve-xmh/applemusic-like-lyrics

## Overview

##### Project type and purpose
- This is a monorepo-managed component library and toolset (“AMLL Series”) providing:
- Core lyric‐display + fluid‐background components (native DOM/TS)
- React & Vue bindings (TS)
- A Rust-based lyric parser (various formats) compiled to WASM
- A Rust FFT engine (for audio analysis) compiled to WASM
- A Rust “player-core” audio engine (decoding, resampling, media‐state)
- A custom WebSocket protocol crate (Rust) for real-time lyrics streaming
- A local desktop player (Tauri + React front-end + Rust back-end)
- A docs site (Astro + TS) and example React “full” player

##### File-structure analysis
- Top-level “packages/” holds each logical module as its own package, mixed TS and Rust crates.
- “packages/core”, “packages/react”, “packages/vue”, “packages/react-full” are front-end UI modules.
- “packages/lyric”, “packages/fft”, “packages/player-core”, “packages/ws-protocol” are Rust crates targeting WASM or desktop.
- “packages/player” is the Tauri-based desktop/web hybrid app (React UI + Tauri’s Rust side).
- “packages/docs” is a static site generating docs & guides.
- Config & build orchestrated via pnpm, Lerna, Rust’s Cargo, wasm-pack, vite.

##### README insights
- Explicit “Main modules” section lists Core, React, Vue, Lyric parser.
- “External tools” section covers the standalone Player and TTML editor.
- Build process: TS build for all “@applemusic‐like‐lyrics/*” and Rust WASM builds.

– TS/DOM Core Library (“@applemusic-like-lyrics/core”)
– React Binding (“@applemusic-like-lyrics/react”)
– Vue Binding (“@applemusic-like-lyrics/vue”)
– React-Full Example App (web demo)
– Docs Site (Astro)
– Rust Lyric Parser WASM (“packages/lyric”)
– Rust FFT WASM (“packages/fft”)
– Rust WS-Protocol Crate (“packages/ws-protocol”)
– Rust Player-Core Engine (desktop & WASM build)
– Tauri Desktop/Web Player App (“packages/player”)
– Core Library produces renderer APIs consumed by React, Vue, React-Full, Player App.
– Rust crates (lyric, fft, player-core) compile to WASM artifacts; these are imported by web modules (Core, Player UI) for parsing & audio analysis.
– WS-Protocol crate provides message definitions used by both Player App’s Rust server side and by remote lyric‐source implementations.
– Player App:
- Front-end (React) ↔ Core Library & WASM modules ↔ Tauri Rust back-end
- Back-end handles audio decode, media state, FFT, invokes Player-Core and FFT crates, streams lyric events over WS internally or externally.
– Docs Site and React-Full Example import Core (and optionally WASM) purely for demonstration.
c. Architectural patterns & principles
– Monorepo modularization: each feature in its own package with independent build.
– Cross‐language binding: JS/TS UI ↔ WASM “native” engines.
– MVVM‐style separation: UI (React/Vue) <-> Core render logic <-> data (lyric parser, audio engine).
– Tauri as a bridge for desktop: packaging TS front-end + Rust back-end.
d. Key technologies
– TypeScript, Vite for building UI components.
– Rust & wasm-pack for compiling to WASM.
– pnpm + Lerna + Nx for monorepo orchestration.
– Tauri for desktop app.
– Astro for docs.
– GLSL shaders for fluid background in Core.
– WebSocket protocol for real-time lyric events.

##### Detail & granularity
- Break out Core subcomponents if needed (LyricRenderer, BackgroundRenderer).
- Surface the data path: Audio Source → Player-Core decode → FFT analysis → Shader parameters → Core fluid shader.
- How lyric parsing modules feed data into Core’s lyric player line/word timing.
- WS‐Protocol definitions are shared types between back-end and any consumer (e.g., remote lyric server or local Tauri IPC).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% TS Packages
    subgraph "TS Packages"
        direction TB
        Core["@applemusic-like-lyrics/core"]:::ts
        React["@applemusic-like-lyrics/react"]:::ts
        Vue["@applemusic-like-lyrics/vue"]:::ts
        ReactFull["React-Full Example App"]:::ts
        Docs["Docs Site (Astro)"]:::docs
    end

    %% Rust WASM Crates
    subgraph "Rust WASM Crates"
        direction TB
        Lyric[(Lyric Parser WASM)]:::rust
        FFT[(FFT Engine WASM)]:::rust
        WSProto[(WS-Protocol Crate)]:::rust
        PlayerCore[(Player-Core WASM)]:::rust
    end

    %% Tauri Desktop/Web Player
    subgraph "Tauri Player App"
        direction TB
        subgraph "Frontend"
            P_FE["Player UI (React + Core)"]:::ts
        end
        subgraph "Backend"
            P_BE["Tauri Rust Backend"]:::desktop
        end
    end

    %% Build-time flows
    Lyric -->|"WASM import"| Core
    FFT -->|"WASM import"| Core
    PlayerCore -->|"WASM import"| Core
    Lyric -->|"WASM import"| ReactFull
    FFT -->|"WASM import"| ReactFull
    PlayerCore -->|"WASM import"| ReactFull

    %% Core to Bindings & Demos
    Core -->|"APIs"| React
    Core -->|"APIs"| Vue
    Core -->|"APIs"| ReactFull
    Core -->|"APIs"| P_FE
    Core -->|"APIs"| Docs

    %% Docs Demo relationships
    Docs -->|"Imports Core"| Core
    Docs -->|"Optional WASM demos"| Lyric
    Docs -->|"Optional WASM demos"| FFT

    %% Player App internal flows
    P_FE -->|"UI calls"| Core
    P_FE -->|"IPC (WS) messages"| P_BE
    P_BE -->|"uses"| PlayerCore
    P_BE -->|"uses"| FFT
    P_BE -->|"uses"| Lyric
    P_BE -->|"defines"| WSProto
    P_FE -->|"uses definitions"| WSProto

    %% Example App flows
    ReactFull -->|"Imports Core"| Core
    ReactFull -->|"Imports WASM"| WSProto

    %% Click Events
    click Core "https://github.com/steve-xmh/applemusic-like-lyrics/tree/full-refractor/packages/core"
    click React "https://github.com/steve-xmh/applemusic-like-lyrics/tree/full-refractor/packages/react"
    click Vue "https://github.com/steve-xmh/applemusic-like-lyrics/tree/full-refractor/packages/vue"
    click ReactFull "https://github.com/steve-xmh/applemusic-like-lyrics/tree/full-refractor/packages/react-full"
    click Docs "https://github.com/steve-xmh/applemusic-like-lyrics/tree/full-refractor/packages/docs"
    click Lyric "https://github.com/steve-xmh/applemusic-like-lyrics/tree/full-refractor/packages/lyric"
    click FFT "https://github.com/steve-xmh/applemusic-like-lyrics/tree/full-refractor/packages/fft"
    click WSProto "https://github.com/steve-xmh/applemusic-like-lyrics/tree/full-refractor/packages/ws-protocol"
    click PlayerCore "https://github.com/steve-xmh/applemusic-like-lyrics/tree/full-refractor/packages/player-core"
    click P_FE "https://github.com/steve-xmh/applemusic-like-lyrics/tree/full-refractor/packages/player"
    click P_BE "https://github.com/steve-xmh/applemusic-like-lyrics/tree/full-refractor/packages/player"

    %% Styles
    classDef ts fill:#cfe2ff,stroke:#0d6efd,color:#0d6efd
    classDef rust fill:#ffe5b4,stroke:#ff8c00,color:#d2691e
    classDef desktop fill:#d1e7dd,stroke:#198754,color:#0f5132
    classDef docs fill:#e2e3e5,stroke:#6c757d,color:#495057
```
