toki/alt

toki c4a457c5c4 docs(agent-ops): domain rule과 로드맵을 operator reliability refactor에 맞게 갱신한다

API domain에 workerclient proxy와 handler responsibility를 추가하고,
worker domain에 backtest engine, storage, provider, socket surface를 명시한다.
Client domain에 socket integration과 push integration 경계를 보강한다.
Operations domain에 agent-test/local과 bin 명령어를 포함하며,
operations domain table에 agent-test/local 경계를 추가한다.

로드맵에 Operator Runtime Reliability Refactor Milestone를 추가하고
현재 활성 Milestone으로 설정하여 Flutter Operator Console 전에
선행할 작업으로 변경한다.

2026-05-31 06:53:24 +09:00

3.5 KiB

Raw Blame History

domain	last_rule_review_commit	last_rule_updated_at
api	`3b1be95e62`	2026-05-31

api

목적 / 책임

클라이언트-facing socket API endpoint와 ALT operator-facing control plane을 제공한다. proto-socket server lifecycle, connection setup, heartbeat timing, ALT protobuf parser registration, API configuration, and worker-facing client proxy lifecycle을 이 경계에서 관리한다.

포함 경로

services/api/cmd/alt-api/ - API service entrypoint
services/api/internal/config/ - API environment configuration
services/api/internal/contracts/ - API-local ALT protobuf parser map
services/api/internal/socket/ - client-facing proto-socket server, session handlers, worker forwarding
services/api/internal/workerclient/ - API-owned proto-socket client proxy to worker
services/api/go.mod - API module dependencies

제외 경로

services/worker/ - long-running jobs and backtest execution
packages/contracts/ - protobuf schema source
packages/domain/ - transport-free domain vocabulary
apps/client/ - UI and client navigation

주요 구성 요소

config.Config - host, port, socket path, heartbeat interval, heartbeat wait
config.Load - environment variable parsing with local fallback defaults
contracts.ParserMap - parser registration for generated ALT protobuf messages
socket.NewServer - proto-socket WsServer construction and session handler registration
socket.marketHandlers, socket.backtestHandlers - request validation and worker forwarding handlers
workerclient.WorkerClient - API-side worker request/response proxy
cmd/alt-api/main.go - signal handling and service lifecycle

유지할 패턴

Read configuration from environment variables with explicit local defaults.
Keep process lifecycle in cmd/alt-api; keep reusable socket construction under internal/socket.
Keep ALT protobuf parser registration under internal/contracts and inject it into proto-socket server construction.
Treat proto-socket as the transport abstraction; ALT payload parsing should be derived from contracts.
Keep client-facing command/query handling in API thin: validate request shape, map transport failures to typed contract errors, and route long-running execution or worker-owned reads through the worker boundary.
Keep worker connectivity lifecycle observable and injectable enough for tests; avoid spreading worker connection state through unrelated API packages.
Keep HelloResponse.capabilities aligned with actually registered API session handlers.

다른 도메인과의 경계

contracts: API imports generated contract packages and owns API-local parser registration, but contract source stays in packages/contracts.
worker: API may forward commands/queries to worker and surface worker availability, but should not run long backtest/import work inline or own worker storage dependencies.
client: API serves client sessions; client UI state and navigation stay in Flutter.

금지 사항

Do not add direct Flutter/client assumptions to API internals.
Do not put scheduled job loops or heavy data processing in the API service.
Do not add worker execution engines, PostgreSQL stores, Redis queues, or provider adapters to API internals.
Do not bypass proto-socket for the main client session path without an explicit architecture update.
Do not require Flutter client or any external operator surface to connect directly to worker runtime surfaces.

3.5 KiB Raw Blame History

api