第一版技術架構

這份文件定義 Bullinv Forge 在第一版最合理的 infra 形態。

核心原則是：

先做出可用 MVP
不要一開始拆太多服務
先讓邊界清楚，再談微服務

一句話結論

第一版最建議的形態是：

1 個前端
1 個主後端
1 個 agent worker
1 個 Postgres
外部平台先透過 adapter 接入主後端

也就是：

modular monolith + separate worker

而不是一開始就做成很多 microservices。

高階架構圖

flowchart TD
    Frontend[Frontend]
    Backend[BackendAPI]
    Worker[AgentRuntimeWorker]
    DB[Postgres]
    Linear[Linear]
    GitHub[GitHub]
    Slack[Slack]

    Frontend --> Backend
    Backend --> DB
    Backend --> Linear
    Backend --> GitHub
    Backend --> Slack
    Backend --> Worker
    Worker --> DB

為什麼這樣最適合第一版

1. 系統數量夠少

你現在要先驗證的是：

task model
agent model
run log
review / approval flow
integration strategy

不是先驗證分散式系統能力。

2. 邊界仍然清楚

即使只有少數幾個服務，也可以先把責任切清楚：

Frontend: 工作面板
Backend: 協調層與 canonical domain
Worker: agent 執行
DB: 系統真相來源

3. 未來仍然能拆

如果之後複雜度提高，你可以再把：

adapter layer
orchestration layer
audit / analytics
notifications

慢慢拆出去。

第一版的服務角色

1. Frontend

負責：

task board
queue
task detail
agent list
run timeline
review / approval UI
workspace settings

這一層是人類使用者的主要入口。

2. Backend API

負責：

auth / workspace
task API
agent registry
run management
review / approval
adapter orchestration
webhook handling
internal canonical model

這是整個平台的大腦與協調層。

建議模組

即使是同一個後端，也建議先邏輯分層：

task service
agent service
run service
review service
workspace service
integration service

3. Agent Runtime Worker

負責：

接任務
執行 agent loop
調用 tools
回報進度
產出 blocker
回傳結果與 summary

為什麼應獨立

長任務不適合卡在 API server
不同 agent 可能需要不同 runtime
未來可能需要 local / remote / sandbox execution

4. Postgres

第一版一個主資料庫就夠。

建議放：

workspaces
users
tasks
agents
runs
comments
reviews
external references
adapter sync metadata

5. External Adapters

第一版不需要做成獨立服務，可以先放在 backend 內部模組。

例如：

LinearAdapter
GitHubAdapter
SlackAdapter

建議的程式結構

apps/
  web/
  api/
  worker/

packages/
  domain/
  adapters/
  agent-runtime/
  shared/

先不要做的事

第一版先不要急著拆成：

task service
review service
notification service
adapter service
workflow service

也先不要急著上：

Kafka
Kubernetes
很重的 service mesh
多資料庫策略

什麼時候才該拆更多服務

當你出現以下情況時，再考慮拆：

runtime 類型很多
webhook / sync 壓力很大
integrations 複雜到影響主 API
audit / analytics 開始變重
多 workspace / 多 tenant 隔離需求變強

第一版建議技術心法

你現在該追求的是：

清楚的 domain boundary
可插拔的 adapter
簡單但穩定的 execution model
可持續演進的 modular monolith

不是：

一開始就把 infra 做得很華麗

最後一句話

Bullinv Forge 第一版最健康的長相，不是十幾個服務，而是一個邊界清楚的主系統，外加一個獨立 worker，先把 task-centric 工作平台跑通。