# AWOOOI 架構記憶地圖 (Architecture Memory)

> AI 模組地圖索引 - 每次新增積木後必須登記

**最後更新**: 2026-03-23
**維護者**: Claude Code + C-Suite

---

## 📦 Python 積木 (packages/)

| 積木名稱 | 職責 | 對外介面 | ADR |
|----------|------|----------|-----|
| **lewooogo-brain** | AI 推論與決策邏輯 | `IProposalEngine`, `IIncidentProcessor` | ADR-008 |
| **lewooogo-data** | 資料抽象與持久化 | `IMemoryProvider`, `IDualMemoryProvider` | ADR-008 |

### lewooogo-brain 模組結構

```
packages/lewooogo-brain/
├── src/lewooogo_brain/
│   ├── interfaces/           # ABC 定義
│   │   ├── proposal_engine.py    → IProposalEngine
│   │   └── incident_processor.py → IIncidentProcessor
│   ├── engines/              # 推論引擎實作
│   │   ├── proposal_engine.py    # 🔲 待實作
│   │   └── incident_engine.py    # 🔲 待搬遷
│   └── skills/               # Skill 動態載入
│       └── loader.py             # 🔲 待實作
```

### lewooogo-data 模組結構

```
packages/lewooogo-data/
├── src/lewooogo_data/
│   ├── interfaces/           # ABC 定義
│   │   └── memory_provider.py    → IMemoryProvider, IDualMemoryProvider
│   └── providers/            # 具體實作
│       ├── redis_memory.py       # 🔲 待實作
│       ├── pg_memory.py          # 🔲 待實作
│       └── dual_memory.py        # 🔲 待實作
```

---

## 📦 TypeScript 積木 (packages/)

| 積木名稱 | 職責 | 對外介面 | ADR |
|----------|------|----------|-----|
| **lewooogo-core** | 前端 Plugin 系統 | `LeWOOOgoPlugin`, `AgentProvider`, `DataAdapter` | ADR-003 |

---

## 🔗 模組依賴關係

```
apps/api (FastAPI BFF)
    ├── lewooogo-brain (AI 積木)
    │   └── lewooogo-data (資料積木)
    └── lewooogo-data (直接引用)

apps/web (Next.js)
    └── lewooogo-core (TS 積木)
```

---

## 📋 介面契約索引

### Python 介面

| 介面 | 位置 | 職責 |
|------|------|------|
| `IProposalEngine` | `lewooogo_brain.interfaces` | 決策提案生成 |
| `IIncidentProcessor` | `lewooogo_brain.interfaces` | 事件聚合處理 |
| `IMemoryProvider` | `lewooogo_data.interfaces` | 單層記憶體存取 |
| `IDualMemoryProvider` | `lewooogo_data.interfaces` | 雙層記憶體 (Working + Episodic) |

### HTTP API 契約

| 端點 | 位置 | 職責 |
|------|------|------|
| `POST /api/v1/incidents/{id}/propose` | `apps/api/src/api/v1/incidents.py` | 生成決策提案 |
| `GET /api/v1/incidents/{id}` | `apps/api/src/api/v1/incidents.py` | 取得事件詳情 |

---

## 🚨 AI 開發者注意事項

1. **新增積木前**: 先讀取此檔案確認命名不衝突
2. **新增積木後**: 必須在此檔案登記職責與對外介面
3. **修改介面前**: 先讀取 `docs/adr/` 確認架構決策
4. **跨模組引用**: 禁止直接 import，必須透過介面抽象