ALT

ALT는 개인용 quant system workspace다. 주식형 instrument의 venue-agnostic 일봉 데이터 기반에서 시작해, 장기적으로 여러 주식시장, 백테스트, 데이터 정규화, 페이퍼 트레이딩, 포트폴리오/리스크 관리, Flutter 클라이언트까지 확장할 수 있는 운영형 구조를 목표로 한다.

Go 서비스와 도구는 루트 go.work로 묶고, Flutter가 web/mobile/desktop 클라이언트 표면을 담당한다. 실시간 통신은 sibling workspace의 ../proto-socket/go를 transport로 사용하며, ALT 애플리케이션 계약은 packages/contracts/proto의 protobuf schema를 원천으로 둔다.

현재 상태

현재 저장소는 초기 scaffold 단계다.

• services/api는 proto-socket WebSocket endpoint scaffold를 제공한다.
• services/worker는 데이터 수집, 정규화, 백테스트, scheduled job을 위한 worker surface다.
• apps/client는 Riverpod과 go_router를 사용하는 Flutter client shell이다. 현재 NomadCode와 같은 top titlebar, 우측 activity rail, 우측 Agent dock 패턴의 workbench scaffold를 포함하며 Agent dock은 공통 agent_shell package를 사용한다.
• packages/contracts에는 alt.v1 protobuf 계약 초안이 있다.
• packages/domain에는 market/backtest vocabulary와 value object skeleton이 있다.
• PostgreSQL 17과 Redis 7 local stack은 deployments/local/docker-compose.yml에 있다.
• 로드맵 진입점은 agent-roadmap/current.md다. 일반 작업에서는 전체 ROADMAP.md를 매번 읽지 않고, 활성 Milestone 문서를 선택해 읽는다.
• market data의 현재 core 범위는 주식/ETF/지수처럼 주식시장 개념을 공유하는 instrument다. Crypto는 거래 구조가 달라 core 주식 모델에 넣지 않고, 향후 별도 asset-class domain에서 공유 가능한 일부 파이프라인만 재사용할지 검토한다.

빠른 시작

# 사용 가능한 entrypoint 확인
bin/dev

# 로컬 PostgreSQL/Redis 실행
docker compose -f deployments/local/docker-compose.yml up -d

# API socket server 실행
cd services/api
go run ./cmd/alt-api

Flutter client는 별도 터미널에서 실행한다.

cd apps/client
flutter run -d chrome --web-port 13030

전체 검증은 루트에서 실행한다.

bin/test
bin/lint
bin/build

주요 명령

목적	명령	비고
개발 entrypoint 확인	bin/dev	infra, API, worker, CLI, client 실행 명령을 출력한다.
전체 테스트	bin/test	Go module test와 Flutter test를 실행한다.
전체 lint/analyze	bin/lint	Go vet와 Flutter analyze를 실행한다.
전체 build	bin/build	Go binary와 Flutter web build를 생성한다.
로컬 infra 실행	docker compose -f deployments/local/docker-compose.yml up -d	PostgreSQL과 Redis를 실행한다.
API 실행	cd services/api && go run ./cmd/alt-api	기본 socket path는 /socket이다.
Worker 실행	cd services/worker && go run ./cmd/alt-worker	현재는 worker scaffold 상태다.
CLI 실행	cd apps/cli && go run ./cmd/alt	운영자 CLI scaffold다.
Client 실행	cd apps/client && flutter run -d chrome --web-port 13030	Flutter web target 기준 개발 실행이다.

구조

경로	역할
services/api/	클라이언트-facing proto-socket API endpoint.
services/worker/	import, normalization, backtest, scheduled job worker surface.
apps/cli/	로컬/운영자 작업용 Go CLI.
apps/client/	Flutter client for web/mobile/desktop. Workbench shell, 우측 Agent dock, Riverpod/go_router app boundary를 포함한다.
packages/contracts/	ALT protobuf contracts and compatibility notes.
packages/domain/	market/backtest shared Go domain model.
deployments/local/	local PostgreSQL and Redis development environment.
bin/	workspace-level helper entrypoints.
agent-ops/	AI agent rules, domain rules, common skills, roadmap templates.

작업 맥락

AI agent는 작업 전에 루트 지침과 관련 domain rule을 먼저 확인한다.

• AGENTS.md
• agent-ops/rules/project/rules.md
• agent-ops/rules/project/domain/*/rules.md
• README 작업은 agent-ops/skills/common/create-readme/SKILL.md를 따른다.
• 로드맵 작업은 agent-roadmap/current.md와 활성 milestone 문서를 기준으로 한다.

중요한 경계는 다음과 같다.

• proto-socket은 transport layer다. ALT application message는 packages/contracts/proto에 둔다.
• packages/domain은 transport나 persistence detail에 의존하지 않는다.
• market domain은 한국장/KIS 필드에 직접 종속되지 않는 global equity venue-agnostic vocabulary를 우선한다.
• 장별 특수값은 canonical column으로 끌어올리기보다 provider adapter, venue metadata, raw payload, 또는 별도 확장 metadata에 격리한다.
• services/api는 socket/session boundary를 담당한다.
• services/worker는 오래 걸리거나 비동기적인 데이터/백테스트 작업을 담당한다.
• apps/client는 Flutter feature-first 구조를 사용한다.
• apps/client의 workbench shell은 UI skeleton 수준이며, 실제 quant 운영 기능은 API/worker/domain headless 경계가 안정화된 뒤 중앙 section에 mount한다.

개발 흐름

• 전체 workspace 검증은 가능한 한 루트 bin/test, bin/lint, bin/build를 우선 사용한다.
• API, worker, client, contracts가 함께 움직이는 변경은 같은 작업 흐름에서 닫는다.
• protobuf generated output은 source schema에서 생성하고 손으로 편집하지 않는다.
• 새 Go module을 추가하면 go.work에 등록한다.
• 로컬 secret이나 개인 설정 파일은 커밋하지 않는다.
• KIS 같은 provider credential은 실제 KIS smoke/live 단계에서만 필요하며, agent runtime secrets는 SOPS + age를 단일 원본으로 둔다.
• 현재 KIS adapter mapping 참조는 로컬 cache의 공식 API 샘플 repo를 우선한다. Credential 없는 mock 검증용 샘플은 services/worker/testdata/providers/kis/ 아래에 secret-free JSON fixture로 둔다.

환경 변수

이름	설명	필수
ALT_API_HOST	API socket server host. 기본값 127.0.0.1.	아니오
ALT_API_PORT	API socket server port. 기본값 18030.	아니오
ALT_API_SOCKET_PATH	API WebSocket path. 기본값 /socket.	아니오
ALT_SOCKET_HEARTBEAT_INTERVAL_SEC	proto-socket heartbeat interval. 기본값 30.	아니오
ALT_SOCKET_HEARTBEAT_WAIT_SEC	proto-socket heartbeat wait. 기본값 10.	아니오
DATABASE_URL	worker에서 사용할 PostgreSQL URL. local fallback: postgres://alt:alt@localhost:15430/alt?sslmode=disable.	아니오
REDIS_URL	worker에서 사용할 Redis URL. local fallback: redis://localhost:16330/0.	아니오

워크스페이스 포트 슬롯

용도	포트
Flutter/web preview	13030
API socket server	18030
worker socket	18031
optional wire/evidence relay	19030
PostgreSQL host publish	15430
Redis host publish	16330

PostgreSQL(5432)과 Redis(6379)의 container 내부 포트는 service DNS/container internal 통신에만 사용하며, host publish 기본값은 위 슬롯으로 통일한다. 이 표는 로컬 checkout과 원격 테스트 runner에서 외부로 노출하는 ALT 포트의 tracked 기준이다. 원격 runner의 실제 host/user/path, artifact/bootstrap endpoint, OpenAI-compatible endpoint, 개인 wire/metrics endpoint는 tracked 문서에 원문을 남기지 않고 local/private rule 또는 secret-only profile에서만 다룬다. ALT에 직접 할당된 public/dev 슬롯이 없으면 tracked 문서에서는 미할당으로 둔다.

기존 smoke 문서나 field/remote 메모가 다른 포트를 가리키면 먼저 위 슬롯과 deployments/local/docker-compose.yml, bin/dev, bin/infra-check, API/worker config 기본값을 대조한 뒤 같은 변경에서 갱신한다. 호환성 확인 전에는 legacy 포트를 새 기본값으로 다시 확정하지 않는다.

Secret 관리

ALT의 KIS provider credential은 실제 provider 호출 단계에서 SOPS + age를 agent runtime secret의 단일 원본으로 둔다. 현재 mock/fixture 테스트 단계에서는 KIS credential이 필요하지 않다. 실제 KIS smoke가 필요해지면 bin/kis-sops-env <command> 또는 배포 환경의 SOPS 복호화 주입 경로로 필요한 process에만 값을 주입한다.

Tracked 문서와 fixture에는 실제 key, token, account number, secret reference를 남기지 않는다. 환경별 운영 메모가 필요하면 git 추적 대상이 아닌 agent-ops/rules/private/에 둔다.

Provider Reference and Fixture

KIS API 참조는 공식 샘플 repo의 로컬 cache를 우선한다. cache 위치와 갱신 방법은 git 추적 제외 private rule인 agent-ops/rules/private/kis-api-local-cache.md에 둔다.

Mock 테스트와 adapter mapping에 필요한 샘플은 services/worker/testdata/providers/kis/ 아래에 secret-free JSON fixture로 둔다. 현재는 Postman export를 필수 입력으로 보지 않는다.

SQLite 보관은 샘플 수가 많아져 검색, 인덱싱, 비교 쿼리가 실제로 필요해진 뒤 검토한다. 초기 adapter mapping과 테스트 fixture에는 diff 가능한 JSON이 기본이다.

참고 문서

• apps/client/README.md
• packages/contracts/README.md
• services/worker/README.md
• services/worker/testdata/providers/kis/README.md
• agent-ops/rules/project/rules.md
• agent-roadmap/current.md
• agent-ops/skills/common/create-roadmap/SKILL.md
• agent-ops/skills/common/update-roadmap/SKILL.md