awoooi/docs/ARCHITECTURE_MEMORY.md

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，必須透過介面抽象