alt/agent-ops/rules/project/domain/api/rules.md

domain	last_rule_review_commit	last_rule_updated_at
api	711dbb9f0c	2026-05-28

api

목적 / 책임

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

포함 경로

• 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/ - proto-socket server construction
• 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
• 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.

다른 도메인과의 경계

• contracts: API imports generated contract packages and owns API-local parser registration, but contract source stays in packages/contracts.
• worker: API may enqueue or observe worker jobs, but should not run long backtest/import work inline.
• 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 bypass proto-socket for the main client session path without an explicit architecture update.