# 架構

本頁說明 ToriiDB 各層如何組合：socket daemon、內嵌 store、各資料庫狀態、持久化與 embedding client。

## 系統總覽

```mermaid
graph TB
    APP[應用程式 process] --> NEW["daemon.New(dir)"]
    NEW -->|socket 有回應| CLI[ModeClient：連線池 unix socket client]
    NEW -->|無存活 socket| SRV[ModeServer：持有 store.Store]
    CLI -->|4-byte 長度 + JSON frame| SOCK["/tmp/toriidb-uid-hash.sock"]
    SOCK --> DISP["dispatch：Session() + Select(db)"]
    SRV --> DISP
    REPL[cmd/test REPL] --> EXEC["Store.Exec 指令路由"]
    DISP --> CORE[store core：KV、JSON 欄位、TTL、掃描、向量]
    EXEC --> CORE
    CORE --> DBS["db_0 ... db_15：RWMutex + Entry map"]
    DBS --> DISK["NNNNNNNN.snap + NNNNNNNN.log 世代"]
    CORE --> EMB["openai.Client (text-embedding-3-small)"]
    EMB --> CACHE["__torii:embed:* 快取項目"]
    CACHE --> DBS
```

## 分層

| 層 | 原始碼 | 職責 |
|---|---|---|
| Socket daemon | `core/daemon/daemon.go`、`socket.go` | 每個資料目錄一個 server；同目錄後續的 `New` 皆成為 client |
| 傳輸協定 | `core/daemon/protocol.go`、`client.go`、`handler.go` | 長度前綴 JSON frame、連線池、op 分派、錯誤種類 |
| 指令路由 | `core/store/exec.go` | 為 REPL 與 `Exec` 呼叫端解析 Redis 風格文字指令 |
| Store 生命週期 | `core/store/store.go` | 16 個延遲載入資料庫、session、過期計時器、關閉時壓縮 |
| Entry 引擎 | `core/store/set.go`、`get.go`、`setField.go`、`del.go`、`incr*.go`、`ttl.go` | 型別偵測、JSON 欄位修改、TTL、解析快取不變條件 |
| 掃描 | `core/store/keys.go`、`find.go`、`query.go`、`filter/` | glob 鍵列舉、值比較、JSON 篩選運算式 |
| 持久化 | `core/store/aof.go`、`gc.go` | 附加 + fsync、snapshot 壓縮、世代退回、垃圾回收 |
| 向量 | `core/store/vector.go`、`vcache.go`、`vsearch.go`、`vsim.go`、`core/openai/client.go` | Embedding、快取、餘弦 Top-K 搜尋 |

## 跨切原則

| 原則 | 體現位置 |
|---|---|
| Socket 身分只由位置決定 | `resolveDir` 依序 `CheckDir` → `filepath.Abs` → `filepath.EvalSymlinks`；socket 固定放 `/tmp`，不讀 `$TMPDIR` |
| 呼叫端不需判斷模式 | `Daemon` 只有一組方法；server 模式行程內分派，client 模式送 frame |
| 每個請求彼此隔離 | daemon 每個請求建立自己的 `Session` 並 `Select` 資料庫，因為選定索引是無鎖 int |
| 記憶體為準、磁碟可重播 | 寫入先更新 map，再附加一行並 sync；啟動時重播 snapshot + log |
| 破壞性覆寫受保護 | 重播失敗時拒絕壓縮；壓縮成功後才回收舊世代 |
| 內部鍵不外洩 | `KEYS`、`FIND`、`QUERY`、`VSEARCH` 跳過 `__torii:*`；點查詢仍可讀 |

## 延伸閱讀

- [Socket Daemon](/zh/socket-daemon)：模式、協定與生命週期
- [持久化](/zh/persistence)：snapshot 與 log 世代
- [核心概念](/zh/core-concepts)：entry、型別、session
- [完整模組圖](https://github.com/pardnchiu/toriidb/blob/master/doc/architecture.zh.md)