awoooi/docs/adr/ADR-003-lewooogo-module-architecture.md

# ADR-003: leWOOOgo 模組化架構

> **狀態**: Accepted
> **日期**: 2026-03-19
> **決策者**: CTO + CEO

## 背景

AWOOOI 需要高度模組化的架構，讓開發者能像組樂高一樣快速組合功能。CEO 命名此引擎為 **leWOOOgo** (樂高 + WOOO)。

傳統 monolithic 架構難以擴展，plugin 架構則能支援生態系統發展。

## 決策

**採用六大積木類別的 Plugin 架構**

```
┌─────────────────────────────────────────────────────────────────┐
│                      leWOOOgo Engine                             │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│   🧱 INPUT ──────→ 🧠 BRAIN ──────→ 📢 OUTPUT                  │
│   (觸發器)          (AI 處理)         (通知)                     │
│       │                │                 │                       │
│       │                ↓                 │                       │
│       │          🔧 ACTION              │                       │
│       │          (執行器)                │                       │
│       │                │                 │                       │
│       └───────→ 📊 DATA ←───────────────┘                       │
│                 (儲存)                                           │
│                                                                 │
│                    🎨 UI                                         │
│                 (介面元件)                                        │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
```

### 六大積木類別

| 類別 | 介面 | 用途 | 範例 |
|------|------|------|------|
| **INPUT** | `TriggerPlugin` | 觸發工作流 | Webhook, Cron, Alert, Email |
| **BRAIN** | `AgentProvider` | AI 處理決策 | LLM Router, RAG, Triage, MCP |
| **OUTPUT** | `NotificationChannel` | 發送通知 | Telegram, Slack, LINE, Email |
| **ACTION** | `ActionExecutor` | 執行操作 | K8s, SSH, Docker, API Call |
| **DATA** | `DataAdapter` | 資料存取 | PostgreSQL, Redis, S3, Vector |
| **UI** | `WidgetComponent` | 介面元件 | Card, Chart, Timeline, Status |

### 核心介面定義

```typescript
// packages/lewooogo-core/src/interfaces/plugin.ts

/** 所有 Plugin 的基礎介面 */
interface LeWOOOgoPlugin {
  readonly id: string
  readonly name: string
  readonly version: string
  readonly category: 'INPUT' | 'BRAIN' | 'OUTPUT' | 'ACTION' | 'DATA' | 'UI'

  initialize(): Promise<void>
  healthCheck(): Promise<HealthStatus>
  shutdown(): Promise<void>
}

/** INPUT 觸發器 */
interface TriggerPlugin extends LeWOOOgoPlugin {
  category: 'INPUT'
  subscribe(handler: TriggerHandler): Unsubscribe
  getSchema(): TriggerSchema
}

/** BRAIN AI 處理器 */
interface AgentProvider extends LeWOOOgoPlugin {
  category: 'BRAIN'
  process(input: AgentInput): Promise<AgentOutput>
  getCapabilities(): AgentCapability[]
}

/** OUTPUT 通知頻道 */
interface NotificationChannel extends LeWOOOgoPlugin {
  category: 'OUTPUT'
  send(message: NotificationMessage): Promise<SendResult>
  getTemplates(): NotificationTemplate[]
}

/** ACTION 執行器 */
interface ActionExecutor extends LeWOOOgoPlugin {
  category: 'ACTION'
  execute(action: ActionRequest): Promise<ActionResult>
  dryRun(action: ActionRequest): Promise<DryRunResult>
  rollback(executionId: string): Promise<RollbackResult>
}

/** DATA 資料適配器 */
interface DataAdapter extends LeWOOOgoPlugin {
  category: 'DATA'
  connect(): Promise<void>
  query<T>(request: QueryRequest): Promise<T>
  disconnect(): Promise<void>
}

/** UI 介面元件 */
interface WidgetComponent extends LeWOOOgoPlugin {
  category: 'UI'
  render(props: WidgetProps): ReactNode
  getConfigSchema(): JSONSchema
}
```

### 資料夾結構

```
packages/
├── lewooogo-core/           # 核心引擎
│   ├── src/
│   │   ├── interfaces/      # 六大介面定義
│   │   ├── registry/        # Plugin 註冊中心
│   │   ├── pipeline/        # 工作流引擎
│   │   └── utils/           # 共用工具
│   └── package.json
│
├── lewooogo-input/          # INPUT 積木
│   ├── src/
│   │   ├── webhook/
│   │   ├── cron/
│   │   ├── prometheus-alert/
│   │   └── email-trigger/
│   └── package.json
│
├── lewooogo-brain/          # BRAIN 積木
│   ├── src/
│   │   ├── llm-router/      # LLM 路由器
│   │   ├── mcp-bridge/      # MCP 整合 (ADR-001)
│   │   ├── triage-engine/   # 告警分級
│   │   └── rag-provider/    # RAG 檢索
│   └── package.json
│
├── lewooogo-output/         # OUTPUT 積木
│   ├── src/
│   │   ├── telegram/
│   │   ├── slack/
│   │   ├── line/
│   │   └── email/
│   └── package.json
│
├── lewooogo-action/         # ACTION 積木
│   ├── src/
│   │   ├── kubernetes/
│   │   ├── ssh/
│   │   ├── docker/
│   │   └── http-api/
│   └── package.json
│
├── lewooogo-data/           # DATA 積木
│   ├── src/
│   │   ├── postgres/
│   │   ├── redis/
│   │   ├── s3/
│   │   └── vector-db/
│   └── package.json
│
└── lewooogo-ui/             # UI 積木
    ├── src/
    │   ├── cards/
    │   ├── charts/
    │   ├── timeline/
    │   └── status-indicators/
    └── package.json
```

## 理由

### 1. 開發者體驗 (DX)

| 傳統方式 | leWOOOgo 方式 |
|---------|--------------|
| 修改核心程式碼 | npm install + 註冊 |
| 重新部署整體 | 熱插拔 Plugin |
| 閱讀大量文檔 | 統一介面 + TypeScript |

### 2. 生態系統潛力

標準介面允許第三方開發 Plugin，形成市場。

### 3. 測試隔離

每個 Plugin 獨立測試，不影響核心引擎。

## 後果

### 優點

- **模組化** 功能獨立開發部署
- **可擴展** 第三方生態系統
- **可測試** 單元測試隔離
- **可維護** 責任分離清晰

### 缺點

- **初期成本** 需建立完整介面規範
- **效能開銷** Plugin 動態載入有成本
- **版本管理** 多 package 需 monorepo 工具

### 風險

| 風險 | 緩解措施 |
|------|---------|
| 介面設計錯誤 | Phase 0 充分討論 + 早期 POC 驗證 |
| Plugin 衝突 | Plugin Registry 管理 + 命名空間隔離 |
| 效能問題 | 關鍵路徑避免過度抽象，效能測試 |

## Monorepo 工具

採用 **pnpm workspace** + **Turborepo**：

```yaml
# pnpm-workspace.yaml
packages:
  - 'apps/*'
  - 'packages/*'
```

```json
// turbo.json
{
  "pipeline": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**"]
    },
    "test": {
      "dependsOn": ["build"]
    }
  }
}
```

## 參考

- [Turborepo](https://turbo.build/)
- [pnpm Workspaces](https://pnpm.io/workspaces)
- ADR-001: MCP Protocol 採用
- 會議記錄: `docs/meetings/2026-03-19_FRONTEND_RESTRUCTURE_STRATEGY.md`