Background & Objectives
本文檔提供架構文檔的填寫框架，用於指導團隊記錄代碼庫的架構標準與設計決策。
This document provides a framework for architectural documentation to guide teams in recording codebase architecture standards and design decisions.
此文檔將：
- 定義架構文檔的結構與章節
- 說明每個章節應記錄的內容
- 記錄從現狀到目標架構的演進路線
- 標記已實現與待實現的基礎能力
- 優先用於指導 LLM 進行開發：文檔結構化且精煉，便於 AI Agent 理解並執行開發任務
This document will:
- Define the structure and sections of architecture documentation
- Explain what should be recorded in each section
- Document the evolution path from current state to target architecture
- Mark implemented and pending capabilities
- Prioritize guiding LLM development: Structured and concise documentation for AI Agent comprehension and task execution
重要原則：文檔不要求所有內容立即實現，而是記錄設計意圖與演進路徑，讓團隊清楚「現在在哪裡」和「要去哪裡」。
Key Principle: Documentation does not require immediate implementation of all content, but rather records design intent and evolution path, making it clear to the team "where we are now" and "where we're going".
Documentation Architecture
以下是架構文檔的建議結構。每個章節包含：
- 📝 填寫指引：說明該章節應記錄的內容
- 現狀 → 目標：記錄實現狀態
Below is the recommended structure for architecture documentation. Each section contains:
- 📝 Guideline: Explains what should be recorded in the section
- Current → Target: Records implementation status
Recommended Documentation Directory Structure
以下是基於本標準的建議 docs/ 目錄組織方式（按章節 1-23 順序）：
Below is the recommended docs/ directory organization based on this standard (following sections 1-23):
docs/
├── README.md # 文檔概覽與導航 / Documentation overview & navigation
├── 01-legend.md # 圖例 / Legend
├── 02-tech-stack.md # 技術棧簡介 / Tech Stack
├── 03-naming-conventions.md # 命名規範 / Naming Conventions (keyNaming)
├── 04-environments.md # 環境管理 / Environments
├── 05-multi-app-architecture.md # 多 App 架構 / Multi-App Architecture (TypeScript Monorepo)
├── 06-business-data-schema.md # 業務數據模型管理 / Business Data Schema Management
├── 07-tenancy-users-permissions.md # 租戶、用戶與權限體系 / Tenancy, Users & Permissions
├── 08-ci-cd.md # 持續集成與部署 / CI & CD
├── 09-testing-framework.md # 測試體系 / Testing Framework
├── 10-api-commands-routes.md # API, 命令與路由 / API, Commands & Routes
├── 11-errors.md # 錯誤處理 / Errors
├── 12-observability.md # 可觀測性 / Observability (Logs, Events, Metrics & Traces)
├── 13-alerts.md # 告警 / Alerts
├── 14-troubleshooting.md # 故障排查 / Troubleshooting
├── 15-async-patterns.md # 異步請求響應規範 / Async Request-Response Patterns
├── 16-eventbus.md # 事件總線機制 / EventBus
├── 17-workflows-tasks.md # 工作流與任務執行 / Workflows & Tasks
├── 18-notification-channels.md # 通知渠道 / Notification Channels
├── 19-open-api-webhooks-llm.md # 開放 API, Webhooks 以及 LLM 可操作性 / APIs & Webhooks with LLM Operability
├── 20-api-key-webhook-management.md # API Key 與 Webhook 管理 / API Key & Webhook Management
├── 21-gdpr-compliance.md # GDPR 合規 / GDPR Compliance
├── 22-i18n.md # 國際化 / Internationalization (i18n)
└── 23-realtime-collaboration.md # 實時協作套件 / Real-time Collaboration Suite
- Legend
每個章節應包括如下說明
Each section should include the following:
現狀 → 目標
- ✅ 現狀：描述代碼庫的現狀
- 🔄 演進中：← 通常用以標記 WIP 中的改造。例如 test 框架遷移。
- ⏳ 待實現：說明現在尚未建立但目標要建立起的內容
Current → Target
- ✅ Current: Describes the current state of the codebase
- 🔄 In Progress: ← Usually marks WIP transformations, e.g., test framework migration
- ⏳ Pending: Explains content not yet established but targeted for implementation
- Tech Stack
📝 填寫指引
列出系統使用的核心技術棧，包括：編程語言及版本、Web 框架、數據庫（關係型/非關係型）、緩存、消息隊列、ORM/查詢構建器、測試框架、部署平台、監控工具等。
📝 Guideline
List the core tech stack used by the system, including: programming languages and versions, web frameworks, databases (relational/non-relational), caching, message queues, ORM/query builders, testing frameworks, deployment platforms, monitoring tools, etc.
現狀 → 目標
- ⏳ 待實現：整個模塊待設計
- Naming Conventions (keyNaming)
📝 填寫指引
定義項目中所有命名標準，包括但不限於：數據庫表名、API 端點、緩存鍵、日誌標籤、環境變量等。
📝 Guideline
Define all naming standards in the project, including but not limited to: database table names, API endpoints, cache keys, log tags, environment variables, etc.
現狀 → 目標
- ⏳ 待實現：整個模塊待設計
- Environments
📝 填寫指引
定義各環境的用途、配置管理方式、環境變量命名規範。
📝 Guideline
Define the purpose of each environment, configuration management approach, and environment variable naming conventions.
現狀 → 目標
- ⏳ 待實現：整個模塊待設計
- Multi-App Architecture (TypeScript Monorepo)
📝 填寫指引
定義 Monorepo 組織方式、新 App 開發流程、App 間依賴管理。
📝 Guideline
Define Monorepo organization approach, new App development workflow, and inter-App dependency management.
現狀 → 目標
- ⏳ 待實現：整個模塊待設計
- Business Data Schema Management
📝 填寫指引
定義業務數據模型的設計規範、此處 business model 特指存在業務意義 (i.e. 如果 model 當做表格輸出，每一個字段都對 non-technical, business role in the system 具有明顯意義)
📝 Guideline
Define design standards for business data models. Here, "business model" specifically refers to models with business significance (i.e., if the model is output as a table, each field has clear meaning to non-technical business roles in the system).
現狀 → 目標
- ⏳ 待實現：整個模塊待設計
- Tenancy, Users & Permissions
📝 填寫指引
定義多租戶架構、用戶體系、權限模型、認證授權機制。
📝 Guideline
Define multi-tenant architecture, user system, permission model, authentication and authorization mechanisms.
現狀 → 目標
- ⏳ 待實現：整個模塊待設計
- CI & CD
📝 填寫指引
定義持續集成與持續部署流程、基礎設施即代碼方案、部署策略、容器化方案、編排工具選型、滾動更新機制、回滾流程、配置管理、健康檢查。
📝 Guideline
Define continuous integration and continuous deployment processes, infrastructure-as-code approach, deployment strategies, containerization solutions, orchestration tool selection, rolling update mechanisms, rollback procedures, configuration management, and health checks.
現狀 → 目標
- ⏳ 待實現：整個模塊待設計
- Testing Framework
📝 填寫指引
定義測試策略、覆蓋率標準、測試工具鏈、Mocking 與 Seed Data 管理。
📝 Guideline
Define testing strategy, coverage standards, testing toolchain, and Mocking & Seed Data management.
現狀 → 目標
- ⏳ 待實現：整個模塊待設計
- API, Commands & Routes
📝 填寫指引
說明 API 設計風格、路由組織方式、版本管理策略、命令層抽象。
Commands 此處特指通過非 API 的方式 (monorepo context) 直接引用其他 package 的方式和設計準則。
📝 Guideline
Explain API design style, route organization approach, version management strategy, and command layer abstraction.
Commands here specifically refer to the approach and design principles for directly referencing other packages through non-API means (monorepo context).
現狀 → 目標
- ⏳ 待實現：整個模塊待設計
- Errors
📝 填寫指引
定義錯誤分類、錯誤碼體系、錯誤響應格式、錯誤處理流程。定義代碼中如何組織內部和對外錯誤。
區分同步操作錯誤與異步操作錯誤的響應設計。
📝 Guideline
Define error classification, error code system, error response format, and error handling procedures. Define how to organize internal and external errors in code.
Distinguish response design for synchronous operation errors vs. asynchronous operation errors.
現狀 → 目標
- ⏳ 待實現：整個模塊待設計
- Observability: Logs, Events, Metrics & Traces
📝 填寫指引
定義日誌、指標、事件的收集標準，standard logging format, metrics and traces 的統一實踐標準，以及監控系統的選型。
📝 Guideline
Define collection standards for logs, metrics, and events, unified practice standards for standard logging format, metrics and traces, and monitoring system selection.
現狀 → 目標
- ⏳ 待實現：整個模塊待設計
- Alerts
📝 填寫指引
定義告警規則、告警級別、通知渠道、值班機制。
📝 Guideline
Define alert rules, alert levels, notification channels, and on-call mechanisms.
現狀 → 目標
- ⏳ 待實現：整個模塊待設計
- Troubleshooting
📝 填寫指引
描述故障排查的標準流程、常用工具、典型問題的排查路徑。
📝 Guideline
Describe standard troubleshooting procedures, commonly used tools, and troubleshooting paths for typical issues.
現狀 → 目標
- ⏳ 待實現：整個模塊待設計
- Async Request-Response Patterns
📝 填寫指引
定義異步請求響應的處理模式、狀態查詢機制、回調通知策略、輪詢與推送方案。
📝 Guideline
Define handling patterns for asynchronous request-response, status query mechanisms, callback notification strategies, and polling vs. push approaches.
現狀 → 目標
- ⏳ 待實現：整個模塊待設計
- EventBus
📝 填寫指引
定義應用內部事件驅動架構，包括事件定義規範、事件發布訂閱機制、事件路由策略、事件處理器註冊與生命週期管理、事件持久化與重放、錯誤處理與重試策略。
此處要明確數據加密、權限隔離等設計決策。
此處並非指定只存在單一的 EventBus，而是強調 Event based process 是現代架構不可缺失的一環 (比如實現多渠道通知和 webhook 推送)，必須有所設計。
📝 Guideline
Define the internal event-driven architecture of the application, including event definition standards, event publish-subscribe mechanisms, event routing strategies, event handler registration and lifecycle management, event persistence and replay, error handling and retry strategies.
Design decisions such as data encryption and permission isolation should be explicitly specified here.
This does not mandate a single EventBus, but emphasizes that event-based processes are an indispensable part of modern architecture (e.g., implementing multi-channel notifications and webhook delivery) and must be designed accordingly.
現狀 → 目標
- ⏳ 待實現：整個模塊待設計
- Workflows & Tasks
📝 填寫指引
後臺自動化任務是任何一個系統不可缺少的一環。
說明後臺流程、異步任務處理機制，包括條件化執行、冪等性、事務處理、補償機制、任務隊列選型、執行策略。
定義長運行任務的進度追蹤機制、實時通知方案。
📝 Guideline
Background automation tasks are an indispensable part of any system.
Explain background processes and asynchronous task processing mechanisms, including conditional execution, idempotency, transaction handling, compensation mechanisms, task queue selection, and execution strategies.
Define progress tracking mechanisms and real-time notification solutions for long-running tasks.
現狀 → 目標
- ⏳ 待實現：整個模塊待設計
- Notification Channels
📝 填寫指引
定義系統通知渠道的架構設計、支持的通知類型（郵件、短信、推送、Webhook 等）、通知模板管理、用戶通知偏好設置、通知發送策略與限流機制。
📝 Guideline
Define the architectural design of system notification channels, supported notification types (email, SMS, push, webhooks, etc.), notification template management, user notification preferences, and notification delivery strategies and rate limiting mechanisms.
現狀 → 目標
- ⏳ 待實現：整個模塊待設計
- APIs & Webhooks with LLM Operability
📝 填寫指引
定義系統能力開放策略，包括 API 設計、Webhook 機制、LLM 如何使用應用的能力、訪問日誌與審計。
📝 Guideline
Define system capability exposure strategies, including API design, webhook mechanisms, how LLMs can utilize application capabilities, and access logging and auditing.
現狀 → 目標
- ⏳ 待實現：整個模塊待設計
- API Key & Webhook Management
📝 填寫指引
定義 API Key 與 Webhook 的生命週期管理、安全策略、UI 設計。
📝 Guideline
Define lifecycle management, security policies, and UI design for API Keys and Webhooks.
現狀 → 目標
- ⏳ 待實現：整個模塊待設計
- GDPR Compliance
📝 填寫指引
定義數據隱私合規機制，包括數據導出、自動刪除、用戶數據查詢、修改和導出權利的實現。
📝 Guideline
Define data privacy compliance mechanisms, including data export, automatic deletion, and implementation of user rights to query, modify, and export data.
現狀 → 目標
- ⏳ 待實現：整個模塊待設計
- Internationalization (i18n)
📝 填寫指引
定義多語言支持策略、翻譯文件組織方式、語言鍵命名規範。
📝 Guideline
Define multi-language support strategy, translation file organization approach, and language key naming conventions.
現狀 → 目標
- ⏳ 待實現：整個模塊待設計
- Real-time Collaboration Suite
📝 填寫指引
定義實時交互功能的架構、統一 SDK、鉴權機制、監控方案。
📝 Guideline
Define architecture for real-time interaction features, unified SDK, authentication mechanisms, and monitoring solutions.
現狀 → 目標
- ⏳ 待實現：整個模塊待設計