docs/architecture.md

系統架構說明 (System Architecture)

Bloom Ware 「小花」專案採用現代化的前後端分離架構，結合多項領先的 AI 技術與穩定可擴展的後端框架。

1. 後端架構 (Backend - FastAPI)

後端採用 Python 的 FastAPI 框架，提供非同步、高效能的 API 服務與 WebSocket 長連接管理。

• app.py: 應用的進入點。負責配置 Lifespan（啟動/關閉事件）、Middleware（如 CORS, CSP）、定義 WebSocket 的連線（/ws），並掛載靜態前端資源。
• core/ (核心邏輯):
  • 資料庫 (database/): 與 Firebase Firestore 進行連線，處理使用者資料、對話紀錄與記憶的 CRUD 操作。
  • 驗證 (auth.py): 處理 JWT Token 生成與解析，並整合 Google OAuth 登入機制。
  • Pipeline (pipeline.py): 負責串接使用者的輸入到大語言模型（LLM）的資料流。
  • 記憶體系統 (memory_system.py): 管理對話上下文，提供 AI 摘要。
• features/ 與 services/ (業務與 AI 服務):
  • 封裝了與 OpenAI 溝通的 ai_service.py。
  • voice_binding.py: 負責聲紋註冊狀態機管理。
  • MCP (Model Context Protocol) 工具集：整合天氣、交通 (TDX)、位置查詢等外部 API。
• websocket/:
  • manager.py: 管理所有連線的使用者會話，處理訊息派發、連線逾時清理等。

2. 前端架構 (Frontend)

本系統將前端拆分為「登入驗證層」與「沉浸式互動層」。

• 登入介面 (bloom-ware-login/out):
  • 基於 Next.js 與 React 構建，編譯為靜態資源後由 FastAPI 掛載於 /login 路徑。
  • 提供 Google 登入、一般信箱登入，以及跳轉至語音註冊的入口。
• 主互動介面 (static/frontend/):
  • 專注於 沉浸式語音體驗 的純靜態應用（HTML/CSS/JS）。
  • 以「小花」的視覺形象（如動態花朵動畫）作為介面核心。
  • 透過 WebRTC/MediaRecorder 擷取音訊，透過 WebSocket 傳送給後端，並將後端回傳的音訊進行播放，且畫面會隨情緒狀態與音量產生動態回饋。

3. 基礎設施與部署 (Infrastructure)

• Docker 化: 提供完整的 Dockerfile，確保在各種環境下執行的一致性。
• Hugging Face Space: 系統原生設計為可直接部署於 Hugging Face Space 上，支援無伺服器架構的容器化執行。
• 排程與背景任務:
  • 啟動時即開啟 asyncio 背景任務，定期清理過期的 WebSocket 會話、壓縮並總結歷史對話，確保長期執行的效能與穩定度。