# f-loat/xiaoplayer architecture

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

- Interactive diagram: https://gitdiagram.com/f-loat/xiaoplayer
- Repository: https://github.com/f-loat/xiaoplayer

## Overview

##### Project type and purpose
- This is a WeChat Mini Program (“小程序”) called “卯卯音乐 (xiaomusic)” that acts as a client to play local or NAS-hosted music on Xiaomi AI speakers.
- It is a full-stack mobile-edge app using:
- A front-end Mini Program built with Weapp-Vite, TailwindCSS, Skyline rendering, and TypeScript.
- A set of serverless Cloud Functions (musictag, proxy, qrcode) running on Tencent Cloud.
- An external xiaomusic backend/service (user-provided NAS or IP-based music server).

##### File structure
- Top-level:
- cloudfunctions/… → multiple micro-endpoints (musictag, proxy, qrcode) each with its own package.json.
- miniprogram/… → WeChat Mini Program source (app.ts, pages/, components/, stores/, utils/).
- config/build files: vite.config.mts, tailwind.config.js, tsconfig.json, project.config.json, postcss.config.js.
- tooling: .eslintrc.js, husky pre-commit hook, prettier.
- Patterns:
- “miniprogram” directory follows the MVC-like page/component structure of WeChat apps.
- Cloudfunctions are pure API facades (stateless, single-responsibility).

##### Key insights from README
- Optional: user may configure the external xiaomusic service URL/IP (with optional basic auth).
- Cloudfunctions support local CORS-safe proxying and QR code generation for sharing.

1. WeChat Mini Program (Mobile App)
- Pages (index, list, player, setting)
- Components (search-bar, music-bar, device-list, lyric, time-bar, etc.)
2. Tencent Cloud Functions
- /musictag → metadata scraping
- /proxy    → HTTP proxy for CORS & domain whitelisting
- /qrcode   → generates QR codes
3. User-configured xiaomusic Service
- Music files (local/NAS)
- Playback API (HTTP interface)
4. Xiaomi AI Speaker (external device)
5. Developer Tooling (WeApp-Vite build & deploy)

- Mini Program → Cloud Functions (API calls to musictag, proxy, qrcode)
- Mini Program → xiaomusic Service (playback control, fetch track list, lyrics)
- Mini Program → Xiaomi AI Speaker via xiaomusic Service (push playback commands)
- Cloud Functions may call external metadata/tag services (for scraping)
- Build & Deploy Tooling → Cloud Functions / Mini Program (deployment pipelines)

c. Architectural patterns & principles
- Frontend-Backend separation (client vs. stateless serverless functions)
- Microservices style in Cloud Functions (single responsibility per endpoint)
- State management in Mini Program (modular stores)
- Custom routing & global toolbar (UI framework extension)

d. Technologies & frameworks
- Mini Program: Weapp-Vite, TailwindCSS, Skyline mode, TypeScript, WXSS, WXML
- Cloud: Tencent Cloud Functions, Node.js, package.json per function
- Build: pnpm, Vite, Tailwind, PostCSS, ESLint, Prettier, Husky

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Client (Mini Program)"
        subgraph "App Entry"
            AppTs["app.ts"]:::frontend
            AppJson["app.json"]:::frontend
            AppWxss["app.wxss"]:::frontend
        end
        subgraph "Pages"
            Home["index page"]:::frontend
            List["list page"]:::frontend
            Player["player page"]:::frontend
            Setting["settings page"]:::frontend
        end
        subgraph "Components"
            Search["search-bar"]:::frontend
            MusicBar["music-bar"]:::frontend
            DeviceList["device-list"]:::frontend
            NavBar["navigation-bar"]:::frontend
            MusicItem["music-item"]:::frontend
            XiaoCell["xiao-cell"]:::frontend
            Radio["radio-player"]:::frontend
            GitHub["github-link"]:::frontend
            Lyric["lyric component"]:::frontend
            LyricLarge["lyric large"]:::frontend
            TimeBar["time-bar"]:::frontend
        end
        subgraph "Stores"
            StoreIndex["stores/index.ts"]:::logic
            Host["host store"]:::logic
            Playlist["playlist store"]:::logic
            LyricStore["lyric store"]:::logic
            Info["info store"]:::logic
            Feature["feature store"]:::logic
            Favorite["favorite store"]:::logic
            XMStore["xiaomusic store"]:::logic
        end
        subgraph "Utils"
            Request["request.ts"]:::logic
            Base64["base64.ts"]:::logic
            Color["color.ts"]:::logic
            UtilsIndex["utils/index.ts"]:::logic
        end
    end

    subgraph "Serverless (Tencent Cloud Functions)"
        MusicTag["musictag()"]:::cloud
        Proxy["proxy()"]:::cloud
        QRCode["qrcode()"]:::cloud
    end

    subgraph "External Services & Devices"
        Service["xiaomusic Service"]:::external
        Speaker["Xiaomi AI Speaker"]:::external
    end

    Search -->|uses| StoreIndex
    MusicBar -->|uses| StoreIndex
    StoreIndex -->|calls| Request
    Request --> MusicTag
    Request --> Proxy
    Request --> QRCode
    Home -->|navigates| List
    List -->|navigates| Player
    Player -->|navigates| Setting
    Player -->|renders| Lyric
    Lyric -->|part| LyricLarge
    Lyric -->|part| TimeBar
    Request --> Service
    Service -->|controls| Speaker

    click AppTs "https://github.com/f-loat/xiaoplayer/blob/main/miniprogram/app.ts"
    click AppJson "https://github.com/f-loat/xiaoplayer/blob/main/miniprogram/app.json"
    click AppWxss "https://github.com/f-loat/xiaoplayer/blob/main/miniprogram/app.wxss"
    click Home "https://github.com/f-loat/xiaoplayer/blob/main/miniprogram/pages/index/index.ts"
    click List "https://github.com/f-loat/xiaoplayer/blob/main/miniprogram/pages/list/index.ts"
    click Player "https://github.com/f-loat/xiaoplayer/blob/main/miniprogram/pages/player/index.ts"
    click Setting "https://github.com/f-loat/xiaoplayer/blob/main/miniprogram/pages/setting/index.ts"
    click Search "https://github.com/f-loat/xiaoplayer/blob/main/miniprogram/components/search-bar/search-bar.ts"
    click MusicBar "https://github.com/f-loat/xiaoplayer/blob/main/miniprogram/components/music-bar/music-bar.ts"
    click DeviceList "https://github.com/f-loat/xiaoplayer/blob/main/miniprogram/components/device-list/device-list.ts"
    click NavBar "https://github.com/f-loat/xiaoplayer/blob/main/miniprogram/components/navigation-bar/navigation-bar.ts"
    click MusicItem "https://github.com/f-loat/xiaoplayer/blob/main/miniprogram/components/music-item/music-item.ts"
    click XiaoCell "https://github.com/f-loat/xiaoplayer/blob/main/miniprogram/components/xiao-cell/xiao-cell.ts"
    click Radio "https://github.com/f-loat/xiaoplayer/blob/main/miniprogram/components/radio-player/radio-player.ts"
    click GitHub "https://github.com/f-loat/xiaoplayer/blob/main/miniprogram/components/github-link/github-link.ts"
    click Lyric "https://github.com/f-loat/xiaoplayer/blob/main/miniprogram/pages/player/components/lyric/lyric.ts"
    click LyricLarge "https://github.com/f-loat/xiaoplayer/blob/main/miniprogram/pages/player/components/lyric/large.ts"
    click TimeBar "https://github.com/f-loat/xiaoplayer/blob/main/miniprogram/pages/player/components/time-bar/time-bar.ts"
    click StoreIndex "https://github.com/f-loat/xiaoplayer/blob/main/miniprogram/stores/index.ts"
    click Host "https://github.com/f-loat/xiaoplayer/blob/main/miniprogram/stores/modules/host.ts"
    click Playlist "https://github.com/f-loat/xiaoplayer/blob/main/miniprogram/stores/modules/playlist.ts"
    click LyricStore "https://github.com/f-loat/xiaoplayer/blob/main/miniprogram/stores/modules/lyric.ts"
    click Info "https://github.com/f-loat/xiaoplayer/blob/main/miniprogram/stores/modules/info.ts"
    click Feature "https://github.com/f-loat/xiaoplayer/blob/main/miniprogram/stores/modules/feature.ts"
    click Favorite "https://github.com/f-loat/xiaoplayer/blob/main/miniprogram/stores/modules/favorite.ts"
    click XMStore "https://github.com/f-loat/xiaoplayer/blob/main/miniprogram/stores/modules/xiaomusic.ts"
    click Request "https://github.com/f-loat/xiaoplayer/blob/main/miniprogram/utils/request.ts"
    click Base64 "https://github.com/f-loat/xiaoplayer/blob/main/miniprogram/utils/base64.ts"
    click Color "https://github.com/f-loat/xiaoplayer/blob/main/miniprogram/utils/color.ts"
    click UtilsIndex "https://github.com/f-loat/xiaoplayer/blob/main/miniprogram/utils/index.ts"
    click MusicTag "https://github.com/f-loat/xiaoplayer/blob/main/cloudfunctions/musictag/index.js"
    click Proxy "https://github.com/f-loat/xiaoplayer/blob/main/cloudfunctions/proxy/index.js"
    click QRCode "https://github.com/f-loat/xiaoplayer/blob/main/cloudfunctions/qrcode/index.js"

    classDef frontend fill:#ade8f4,stroke:#0077b6,color:#03045e
    classDef logic fill:#caf0f8,stroke:#0096c7,color:#023e8a
    classDef cloud fill:#ffe5d9,stroke:#fb8b24,color:#9b2226
    classDef external fill:#e0c3fc,stroke:#7209b7,color:#3a0ca3
```
