# 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-roadmap/current.md`다. 일반 작업에서는 전체 `ROADMAP.md`를 매번 읽지 않고, 활성 Milestone 문서를 선택해 읽는다.

## 빠른 시작

```bash
# 사용 가능한 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는 별도 터미널에서 실행한다.

```bash
cd apps/client
flutter run -d chrome
```

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

```bash
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-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-roadmap/current.md`
- `agent-ops/skills/common/create-roadmap/SKILL.md`
- `agent-ops/skills/common/update-roadmap/SKILL.md`