# 架构设计规范 — SyncLive

SyncLive（同步直播，对标 SyncTV）的整体架构与模块划分说明。

## 分层架构

```
浏览器 (SolidJS SPA)
        │  HTTP / SSE / WebRTC (信令经服务端反代，媒体直连 SFU)
        ▼
控制面 (Go)
  ├─ gRPC + JSON 网关        # protobuf 定义的统一控制契约
  ├─ 鉴权 (Casbin RBAC + JWT) # 登录、权限校验、用户管理
  ├─ 房间拓扑 (roomHub)       # 内存态 + 嵌入式 libSQL 持久化
  └─ 媒体面反代 (httputil)    # SRS / Cloudflare 信令与 HLS 反代
        │
        ▼
媒体面 (SFU Provider 抽象)
  ├─ Cloudflare Realtime      # 主 SFU（托管，低延迟扇出）
  └─ SRS                      # 本地/对照 SFU（WHIP/WHEP + HLS/FLV 同出）
```

## 模块职责

- `api/`：protobuf 控制面契约（`SyncLive` 服务），单一事实来源，经 `buf generate` 生成 Go 代码到 `gen/`。
- `internal/config/`：运行参数与环境变量加载，含正式环境密钥校验（`Validate`）。
- `internal/db/`：嵌入式 libSQL 持久化（房间分发拓扑），仅 file:/:memory: 模式。
- `internal/auth/`：Casbin RBAC 模型与策略、JWT 签发校验、用户存储。
- `internal/sfu/`：SFU 后端 Provider 抽象（Cloudflare / SRS），统一 `BackendInfo` 与能力查询。
- `internal/server/`：HTTP/gRPC 服务装配、JSON 网关、房间与聊天 SSE、媒体反代、静态 UI 嵌入。
- `cmd/server/`：进程入口，装配配置、服务与优雅关闭。
- `web/`：前端单页应用（SolidJS + TanStack + Ark UI + Tailwind v4），构建产物由 Go embed 内联。

## 设计约束

- 控制面与媒体面分离：浏览器只与服务端交换 SDP/信令，SFU 凭证不出服务端。
- 多 SFU 后端可同时承载同一路发布（分流），拓扑由 `WatchRoom` / SSE 实时广播。
- 持久化默认嵌入式、零外部依赖；远程 libSQL 仅作可选项。
- 正式环境密钥必须显式配置，禁止内置弱密码与不安全默认密钥。