ALT

ALT는 개인용 quant system workspace다. 한국장 일봉 기반 MVP에서 시작해, 장기적으로 미국장, 백테스트, 데이터 정규화, 페이퍼 트레이딩, 포트폴리오/리스크 관리, 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이다.
• 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-ops/roadmap/current.md다. 일반 작업에서는 전체 ROADMAP.md를 매번 읽지 않고, 활성 Milestone 문서를 선택해 읽는다.

빠른 시작

# 사용 가능한 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

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

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	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.
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-ops/roadmap/current.md와 활성 milestone 문서를 기준으로 한다.

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

• proto-socket은 transport layer다. ALT application message는 packages/contracts/proto에 둔다.
• packages/domain은 transport나 persistence detail에 의존하지 않는다.
• services/api는 socket/session boundary를 담당한다.
• services/worker는 오래 걸리거나 비동기적인 데이터/백테스트 작업을 담당한다.
• apps/client는 Flutter feature-first 구조를 사용한다.

개발 흐름

• 전체 workspace 검증은 가능한 한 루트 bin/test, bin/lint, bin/build를 우선 사용한다.
• API, worker, client, contracts가 함께 움직이는 변경은 같은 작업 흐름에서 닫는다.
• protobuf generated output은 source schema에서 생성하고 손으로 편집하지 않는다.
• 새 Go module을 추가하면 go.work에 등록한다.
• 로컬 secret이나 개인 설정 파일은 커밋하지 않는다.

환경 변수

이름	설명	필수
ALT_API_HOST	API socket server host. 기본값 127.0.0.1.	아니오
ALT_API_PORT	API socket server port. 기본값 8080.	아니오
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 있음.	아니오
REDIS_URL	worker에서 사용할 Redis URL. local fallback 있음.	아니오

참고 문서

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