---
domain: api
last_rule_review_commit: 704f1eb23260d5a82b0b134eab6c6470b1b4256a
last_rule_updated_at: 2026-06-24
---

# 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을 이 경계에서 관리한다. Market, backtest, paper trading, live trading, scheduler query 요청은 API에서 shape만 검증하고 worker-owned surface로 전달한다.

## 포함 경로

- `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/api/go.sum` - API module dependency checksums

## 제외 경로

- `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 timing, WebSocket origin patterns, and worker socket URL
- `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` - `ListInstruments`, `ListBars`, `ImportDailyBars`, `AggregateMonthlyBars`, and `SchedulerRefreshStatus` validation plus worker forwarding
- `socket.backtestHandlers` - start, list, detail, result, and compare backtest request validation plus worker forwarding
- `socket.paperHandlers` - start/state/order lifecycle paper trading validation plus worker forwarding
- `socket.apiLiveHandlers` - live capability, order lifecycle, risk/kill switch, account sync, and audit query validation plus worker forwarding
- `workerclient.WorkerClient` - API-side worker request/response proxy for market, backtest, paper, live, and scheduler contracts
- `workerclient.sendTyped` - shared worker forwarding path for timeout, unavailable, and context cancellation mapping
- `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, broker calls, scheduler state, storage-backed reads, and worker-owned writes 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.
- Bound forwarded worker calls with a context timeout and return typed `ErrorInfo` payloads instead of leaking Go handler errors to clients.
- Keep API-local parser registration complete for every ALT protobuf message that can cross the client/API or API/worker proto-socket boundary.

## 다른 도메인과의 경계

- **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 backtest/import/aggregation/scheduler/paper/live work inline or own worker storage/provider 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, scheduler runners, broker clients, paper/live trading engines, 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.