# akudamatata/solara architecture

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

- Interactive diagram: https://gitdiagram.com/akudamatata/solara
- Repository: https://github.com/akudamatata/solara

## Overview

1. **整体形态**
   这是一个“静态前端 + Cloudflare Pages Functions 轻量后端”的音乐播放器。主应用界面由 `index.html`、`js/index.js` 和 CSS 构成；后端能力集中在 `functions/`，主要负责接口聚合、访问控制、音频代理和可选的数据持久化。

2. **前端应用壳**
   `index.html` 是播放器主入口，加载公共样式、桌面/移动端样式和核心脚本。页面本身更像一个单页应用容器：搜索区、曲库结果、播放队列、收藏列表、歌词面板、底部控制栏等都由前端脚本动态驱动，而不是多页面跳转。

3. **核心交互与状态管理**
   `js/index.js` 是业务中枢，负责播放器状态、搜索、播放、队列、收藏、导入导出、播放模式、歌词同步、调试面板以及“探索雷达”补歌逻辑。它把本地 UI 操作和后端数据源解耦：前端只关心用户交互和状态流转，具体数据源的请求细节由后端代理统一处理。

4. **移动端与桌面端分层**
   样式分为 `css/style.css`（通用主题变量与基础视觉）、`css/desktop.css`（桌面布局）和 `css/mobile.css`（竖屏移动端适配）。`js/mobile.js` 专注移动端交互和手势/布局切换，说明这个项目不是简单的响应式页面，而是针对手机竖屏做了独立的交互分支。

5. **数据源聚合层**
   `functions/api/` 下是一组 API 入口，承担“统一数据源”的职责。README 说明播放器可切换不同曲库，并支持搜索、播放、下载全流程；这些能力在架构上依赖后端函数对多个外部音乐接口做聚合和转发，而不是让浏览器直接面对各个第三方接口。

6. **音频直链代理**
   `functions/proxy.ts` 是音频代理边界，用于处理跨域和直链获取问题。它把第三方音频资源通过 Cloudflare 侧转发出来，使前端能稳定拿到可播放/可下载的音频地址，同时避免浏览器直接跨域访问外部资源带来的限制。

7. **访问控制**
   `functions/_middleware.ts` 和 `login.html` 共同构成站点口令保护。中间件负责在 Pages Functions 层拦截未登录访问，并把用户导向登录页；`PASSWORD` 环境变量决定是否启用这层访问控制。这个边界在架构上位于“静态站点入口”之前。

8. **持久化与回退机制**
   `functions/api/storage.ts` 配合 Cloudflare D1 做服务端持久化，README 里明确分成两张表：`playback_store` 和 `favorites_store`。这意味着播放状态/队列与收藏数据被分离存储，降低互相污染的风险。若未绑定 D1，前端自动退回到浏览器 `localStorage`，形成“云端优先、本地兜底”的存储策略。

9. **封面取色与视觉联动**
   `functions/palette.ts` 提供封面取色算法，支持根据当前曲目封面生成动态背景或主题色。它是播放器视觉层的重要服务，和前端的玻璃拟态、亮暗模式、沉浸式背景联动，形成“曲目信息驱动 UI 皮肤”的体验闭环。

10. **外部依赖与运行环境**
   这个项目的运行核心依赖 Cloudflare Pages/Functions 和可选的 D1 数据库；外部音乐接口则由后端代理统一对接。前端运行在浏览器中，负责 UI、音频播放、歌词滚动和本地状态；后端运行在边缘函数环境中，负责认证、数据聚合、代理和存储。

11. **关键数据流**
   典型流程是：用户在前端输入关键词 → `js/index.js` 发起搜索 → `functions/api/*` 访问聚合接口 → 返回歌曲列表 → 前端渲染、加入队列或收藏 → 状态同步到 `storage.ts`（优先 D1，失败则 localStorage）→ 播放时通过 `proxy.ts` 获取音频直链 → 前端 HTML5 音频/播放器控制播放与进度。

12. **界面与数据边界**
   这个仓库的边界划分很清晰：HTML/CSS/JS 只负责体验和状态；`functions/` 负责所有需要跨域、鉴权或持久化的能力。对架构图来说，可以把它画成一个前端播放壳，旁边挂一个 Cloudflare 边缘服务层，再往外连接第三方音乐接口与 D1 数据库。

Main entry points: [`index.html`](https://github.com/akudamatata/solara/blob/main/index.html) (Player shell), [`js/index.js`](https://github.com/akudamatata/solara/blob/main/js/index.js) (Player core), [`functions/api/storage.ts`](https://github.com/akudamatata/solara/blob/main/functions/api/storage.ts) (Storage API), [`functions/api`](https://github.com/akudamatata/solara/tree/main/functions/api) (Music APIs)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend app"]
  node_index_html["Player shell<br/>entry page<br/>[index.html]"]
  node_style_css["Theme base<br/>global css<br/>[style.css]"]
  node_desktop_css["Desktop layout<br/>desktop css<br/>[desktop.css]"]
  node_mobile_css["Mobile layout<br/>mobile css<br/>[mobile.css]"]
  node_index_js["Player core<br/>client app<br/>[index.js]"]
  node_mobile_js["Mobile UX<br/>touch interactions<br/>[mobile.js]"]
  node_login_html["Login page<br/>auth page<br/>[login.html]"]
end

subgraph group_edge["Cloudflare edge"]
  node_middleware{{"Access gate<br/>edge middleware<br/>[_middleware.ts]"}}
  node_api_login["Login API<br/>auth endpoint<br/>[login.ts]"]
  node_api_storage[("Storage API<br/>persistence endpoint<br/>[storage.ts]")]
  node_api_catalog["Music APIs<br/>aggregation layer"]
  node_proxy{{"Audio proxy<br/>media proxy<br/>[proxy.ts]"}}
  node_palette(("Palette service<br/>visual service<br/>[palette.ts]"))
  node_vendor_lib["Vendor libs<br/>shared library"]
end

subgraph group_external["External systems"]
  node_d1[("Cloudflare D1<br/>database")]
  node_music_sources["Music sources<br/>third-party services"]
end

node_index_html -->|"loads"| node_index_js
node_index_html -->|"styles"| node_style_css
node_index_html -->|"adapts"| node_desktop_css
node_index_html -->|"adapts"| node_mobile_css
node_index_html -->|"enhanced by"| node_mobile_js
node_index_js -->|"searches"| node_api_catalog
node_index_js -->|"syncs"| node_api_storage
node_index_js -->|"plays via"| node_proxy
node_index_js -->|"themes"| node_palette
node_middleware -->|"redirects to"| node_login_html
node_middleware -->|"guards"| node_api_login
node_api_login -->|"authorizes"| node_api_storage
node_api_catalog -->|"queries"| node_music_sources
node_proxy -->|"relays"| node_music_sources
node_api_storage -->|"persists to"| node_d1
node_api_storage -.->|"falls back"| node_music_sources
node_palette -->|"reads covers from"| node_music_sources
node_vendor_lib -->|"supports"| node_api_catalog
node_vendor_lib -->|"supports"| node_proxy

click node_index_html "https://github.com/akudamatata/solara/blob/main/index.html"
click node_style_css "https://github.com/akudamatata/solara/blob/main/css/style.css"
click node_desktop_css "https://github.com/akudamatata/solara/blob/main/css/desktop.css"
click node_mobile_css "https://github.com/akudamatata/solara/blob/main/css/mobile.css"
click node_index_js "https://github.com/akudamatata/solara/blob/main/js/index.js"
click node_mobile_js "https://github.com/akudamatata/solara/blob/main/js/mobile.js"
click node_login_html "https://github.com/akudamatata/solara/blob/main/login.html"
click node_middleware "https://github.com/akudamatata/solara/blob/main/functions/_middleware.ts"
click node_api_login "https://github.com/akudamatata/solara/blob/main/functions/api/login.ts"
click node_api_storage "https://github.com/akudamatata/solara/blob/main/functions/api/storage.ts"
click node_api_catalog "https://github.com/akudamatata/solara/tree/main/functions/api"
click node_proxy "https://github.com/akudamatata/solara/blob/main/functions/proxy.ts"
click node_palette "https://github.com/akudamatata/solara/blob/main/functions/palette.ts"
click node_vendor_lib "https://github.com/akudamatata/solara/tree/main/functions/lib/vendor"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_index_html,node_style_css,node_desktop_css,node_mobile_css,node_index_js,node_mobile_js,node_login_html toneBlue
class node_middleware,node_api_login,node_api_storage,node_api_catalog,node_proxy,node_palette,node_vendor_lib toneAmber
class node_d1,node_music_sources toneMint
```

## Components

### Frontend app

Static player UI and client-side state

- [Player shell](https://github.com/akudamatata/solara/blob/main/index.html): entry page · Main HTML container for the player UI · `index.html`
- [Theme base](https://github.com/akudamatata/solara/blob/main/css/style.css): global css · Shared visual variables and base styling · `css/style.css`
- [Desktop layout](https://github.com/akudamatata/solara/blob/main/css/desktop.css): desktop css · Desktop-specific layout and presentation · `css/desktop.css`
- [Mobile layout](https://github.com/akudamatata/solara/blob/main/css/mobile.css): mobile css · Mobile-specific layout and responsive styling · `css/mobile.css`
- [Player core](https://github.com/akudamatata/solara/blob/main/js/index.js): client app · Search, playback, queue, favorites, lyrics, import/export, and state orchestration · `js/index.js`
- [Mobile UX](https://github.com/akudamatata/solara/blob/main/js/mobile.js): touch interactions · Mobile gestures and layout-specific interaction logic · `js/mobile.js`
- [Login page](https://github.com/akudamatata/solara/blob/main/login.html): auth page · Password entry page for protected access · `login.html`

### Cloudflare edge

Functions, middleware, proxy, and optional persistence

- [Access gate](https://github.com/akudamatata/solara/blob/main/functions/_middleware.ts): edge middleware · Intercepts requests and enforces password protection · `functions/_middleware.ts`
- [Login API](https://github.com/akudamatata/solara/blob/main/functions/api/login.ts): auth endpoint · Handles authentication-related requests · `functions/api/login.ts`
- [Storage API](https://github.com/akudamatata/solara/blob/main/functions/api/storage.ts): persistence endpoint · Persists playback state and favorites with cloud and local fallback · `functions/api/storage.ts`
- [Music APIs](https://github.com/akudamatata/solara/tree/main/functions/api): aggregation layer · Unified API surface for music search and catalog access · `functions/api`
- [Audio proxy](https://github.com/akudamatata/solara/blob/main/functions/proxy.ts): media proxy · Fetches or relays playable audio sources through the edge · `functions/proxy.ts`
- [Palette service](https://github.com/akudamatata/solara/blob/main/functions/palette.ts): visual service · Extracts cover colors for dynamic theming · `functions/palette.ts`
- [Vendor libs](https://github.com/akudamatata/solara/tree/main/functions/lib/vendor): shared library · Bundled third-party helper code used by edge functions · `functions/lib/vendor`

### External systems

Third-party music sources and Cloudflare services

- **Cloudflare D1**: database · Optional server-side storage for playback and favorites
- **Music sources**: third-party services · External music providers and direct media hosts

## Connections

- Player shell → Player core: loads · Bootstraps the client player runtime
- Player shell → Theme base: styles · Applies the base visual theme
- Player shell → Desktop layout: adapts · Adds desktop-specific layout rules
- Player shell → Mobile layout: adapts · Adds mobile-specific layout rules
- Player shell → Mobile UX: enhanced by · Activates mobile interaction behavior
- Player core → Music APIs: searches · Requests catalog and search results
- Player core → Storage API: syncs · Saves and restores playback state and favorites
- Player core → Audio proxy: plays via · Obtains playable audio through the edge proxy
- Player core → Palette service: themes · Uses cover colors to update the visual experience
- Access gate → Login page: redirects to · Sends unauthenticated users to the login page
- Access gate → Login API: guards · Applies access control to protected routes
- Login API → Storage API: authorizes · Controls access to persisted user data
- Music APIs → Music sources: queries · Aggregates results from external music providers
- Audio proxy → Music sources: relays · Forwards requests to external media hosts
- Storage API → Cloudflare D1: persists to · Uses D1 when available for server-side storage
- Storage API → Music sources: falls back · Local browser storage remains available when cloud persistence is absent
- Palette service → Music sources: reads covers from · Derives theme colors from remote artwork
- Vendor libs → Music APIs: supports · Shared helper code used by the edge API layer
- Vendor libs → Audio proxy: supports · Shared helper code used by proxy logic
