# 架構

本頁以一張概覽圖說明 PodRun 的 CLI、遠端主機與 API Server 之間的層級關係。

## 系統概覽

```mermaid
graph LR
    subgraph 本地主機
        CLI[podrun CLI<br/>cmd/cli]
        API[API Server<br/>cmd/api :8080]
        DB[(SQLite)]
    end
    subgraph 遠端主機
        Dir[/home/podrun/名稱_雜湊/]
        Compose[Podman Compose]
        K3s[k3s 未完成]
    end
    CLI -->|rsync over sshpass| Dir
    CLI -->|ssh 指令| Compose
    CLI -.->|未完成| K3s
    Compose --> Dir
    CLI -->|HTTP POST| API
    API --> DB
```

## 分層

| 層 | 套件 | 職責 |
|---|---|---|
| 入口 | `cmd/cli` | 載入 `.env`、檢查依賴與環境變數、測試 SSH、分派指令 |
| 入口 | `cmd/api` | 決定 `DB_PATH`、開啟 SQLite、啟動 HTTP Server |
| 指令 | `internal/command` | 解析參數、推導本地與遠端路徑、執行 `up`／`clear`／轉送指令、回報 API |
| 工具 | `internal/utils` | `sshpass` 包裝（`SSHRun`、`SSEOutput`、`SSHTest`）、依賴安裝、本機 MAC／IP／Hostname |
| HTTP | `internal/handler` | Gin 路由與 JSON 綁定 |
| 儲存 | `internal/database` | `pods`／`records` 的 upsert、update、insert、list |
| 模型 | `internal/model` | `Pod`、`Record`、`User` 結構 |

## 跨切原則

- **遠端零安裝**：遠端只需 SSH 與 Podman，所有邏輯在本地 CLI 透過 SSH 指令完成
- **不動原始檔**：本地 compose 檔不修改，改寫只發生在遠端副本 `docker-compose.podrun.yml`
- **紀錄失敗不阻斷部署**：`removePod()` 與 `recordPod()` 的錯誤被忽略；只有 `up` 結尾的 `upsertPod()` 失敗會回傳錯誤

## 延伸閱讀

模組級圖、`up` 時序圖與狀態機見 [doc/architecture.zh.md](https://github.com/pardnchiu/PodRun/blob/master/doc/architecture.zh.md)。