# 系統架構

瞭解 Netstamp 的控制器、探測器執行階段、資料模型、API 合約產生流程、前端套件、儲存層與背景工作。

Netstamp 由自行託管的控制器與分散式探測器 agent 組成。程式碼儲存庫集中管理可執行服務、API 合約、應用程式、UI 設計系統、說明文件與部署資源。

## 執行階段拓撲

```text
                                  +-----------------------+
Browser / API client -----------> | Controller HTTP :8080 |
                                  | auth, projects, API   |
                                  +-----------+-----------+
                                              |
                                              v
                                  PostgreSQL + TimescaleDB
                                              ^
                                              |
Linux probe agents ---- hello / heartbeat / assignments / result batches
                                              |
                                              +---- alert evaluator
                                              +---- assignment refresh worker
                                              +---- notification outbox worker
```

正式環境映像檔讓控制器從 `/app/web` 提供建置完成的 React 應用程式。瀏覽器路由找不到對應檔案時會回傳 `index.html`；`/api/v1` 仍是 API；`/healthz` 對應 API 健康狀態；`/metrics` 則提供控制器指標。

## 控制器邊界

Go 後端採用模組化單體架構：

- **Transport（傳輸層）**負責 HTTP、驗證、輸入檢查、回應 DTO 與狀態碼對應。
- **Application（應用層）**負責使用案例編排、授權、介面、事件與追蹤。
- **Domain（領域層）**負責穩定的資料模型與專案權限政策。
- **Infrastructure（基礎設施層）**實作 PostgreSQL/sqlc 資料存取層、權杖、密碼雜湊、外部身分服務用戶端與通知傳送。
- **Composition（組合層）**載入設定並組合具體實作。

HTTP handler 不會直接存取資料庫。應用層服務只依賴範圍明確的介面，並負責其功能的行為語意。

## 探測器執行階段

Agent 的排程、背景工作、結果佇列與 HTTP 用戶端各自獨立。它會：

1. 完成驗證並回報執行階段能力；
2. 定期傳送心跳訊號與 IP 版本能力更新；
3. 輪詢目前有效的指派；
4. 將到期工作排入有數量上限的背景工作池（worker pool）；
5. 執行 Ping、TCP、HTTP 或 Traceroute；
6. 暫存結果，並依退避策略重試批次提交。

每個探測器的執行參數都由本機 `NETSTAMP_PROBE_*` 設定控制。控制器只傳送指派，不會下發背景工作或佇列設定。

## 資料儲存

PostgreSQL 儲存身分、工作階段、專案、標籤、探測器、檢查、指派、警示、通知、公開頁面與系統管理設定。TimescaleDB hypertable 與 continuous aggregate 則支援具型別的 Ping、TCP、HTTP、Traceroute 歷史結果，以及依時間範圍調整的查詢。

資料庫遷移使用 Goose SQL 檔案，並在應用程式容器啟動前完成。sqlc 會依查詢檔產生具型別的資料存取程式碼。

## API 合約產生流程

```text
api/*.tsp
   |
   +--> docs/public/openapi.json
   +--> server embedded openapi.json
   +--> web/src/shared/api/openapi.d.ts
   +--> Scalar API explorers
```

TypeSpec 是 API 合約的唯一準據。`pnpm generate:openapi` 會更新所有產生的使用端，因此控制器與說明文件網站發布的合約，會和 Web 用戶端使用的型別保持一致。

## 前端與說明文件

- `web/` 是使用 React 19 與 Vite 的應用程式，包含以專案為範圍的路由，並以 TanStack Query 管理伺服器狀態。
- `packages/ui/` 負責共用元件與 `--ns-*` 設計權杖。
- `docs/` 是靜態 Astro 網站，會發布產品說明文件、OpenAPI 瀏覽器與建置完成的 Storybook。

Web 與 Docs 都使用共用 UI 套件。說明文件內容存放在 Astro 內容集合，讓導覽、搜尋、頁面順序、編輯連結、網站地圖與上一頁／下一頁連結都能從 frontmatter 產生。

## 驗證層面

瀏覽器使用者透過伺服器端工作階段驗證；個人 API 權杖具有權限範圍，並同時受到目前專案權限限制，驗證格式為 `Bearer nst_pat_...`；探測器 agent 則使用 `Authorization: Probe ...`。這三種憑證刻意設計成不能互換。

目前的 Netstamp 架構沒有 GraphQL API、外部訊息佇列、物件儲存相依服務，也沒有 DNS 專用的探測器執行器。