# ALT 프로젝트 규칙

## 응답 언어

- 기본 응답은 한국어로 작성한다.
- 코드 식별자, 명령어, 경로, 에러 메시지는 원문 영어를 유지한다.
- 설계 선택을 설명할 때는 ALT의 quant workspace 맥락과 연결해서 짧게 근거를 남긴다.

## 프로젝트 개요

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

## 주요 구조

| 경로 | 역할 |
|------|------|
| `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/` | shared Go domain model for market and backtest concepts |
| `deployments/local/` | local PostgreSQL and Redis development environment |
| `bin/` | workspace-level helper entrypoints |

## 기술 스택

- Go 1.22 multi-module workspace via `go.work`.
- `git.toki-labs.com/toki/proto-socket/go` is consumed through a local replace to `../proto-socket/go`.
- `services/api` uses `nhooyr.io/websocket` through proto-socket server/client wrappers.
- Contracts are protobuf schemas under `packages/contracts/proto/alt/v1`.
- Flutter client uses Material 3, Riverpod, and `go_router`.
- Local infrastructure uses Docker Compose with PostgreSQL 17 and Redis 7.

## 통신 규칙

- ALT가 소유한 runtime boundary 사이의 application message 통신은 proto-socket과 `packages/contracts/proto`의 ALT protobuf payload로 통일한다.
- 기본 runtime topology는 `client -> services/api -> services/worker`다. client는 worker를 직접 제어하지 않고 `services/api`를 단일 operator-facing control plane으로 사용한다.
- client-api, api-worker, worker-sidecar처럼 별도 process나 service 사이에서 ALT domain request/response, event, command를 주고받으면 기본값은 proto-socket이다.
- 같은 process 안의 함수 호출, Go interface, Dart provider 호출은 runtime 통신부로 보지 않는다.
- PostgreSQL SQL, Redis command/queue/cache, filesystem, process/stdout, local migration/codegen/dev tooling은 해당 목적의 native protocol을 사용한다.
- KIS, Mattermost, Firebase, Nexo plugin, OS platform channel처럼 ALT 외부 시스템이나 platform integration과 통신할 때는 해당 외부 protocol을 adapter 경계 안에서 사용한다.
- proto-socket이 아닌 ALT-owned runtime protocol을 새로 도입하려면 구현 전에 프로젝트 규칙 또는 명시적 architecture 문서를 갱신하고 예외 사유를 남긴다.

## 프로젝트 컨벤션

- 루트 작업은 `bin/dev`, `bin/test`, `bin/lint`, `bin/build`를 우선 사용한다.
- Go 모듈 경계를 넘는 import는 `go.work`에 등록된 모듈 기준으로 유지한다.
- protobuf generated client/server 코드는 schema에서 생성하고 손으로 편집하지 않는다.
- `packages/domain`은 business vocabulary와 value object를 담고, transport나 persistence detail에 의존하지 않는다.
- `services/api`는 socket/session boundary를 담당하고, domain 계산이나 worker job 실행을 직접 떠안지 않는다.
- `services/api`는 얇은 control plane으로서 client-facing 요청을 받고 worker 실행/조회 경계로 중계한다.
- `services/worker`는 데이터 수집, 정규화, backtest 실행, scheduled job처럼 오래 걸리거나 비동기적인 일을 담당한다.
- Flutter client는 `lib/src/app`에 앱 shell/router를 두고, 기능 화면은 `lib/src/features/feature-name/presentation` 패턴 아래에 둔다.
- runtime configuration은 환경변수를 우선하고 로컬 개발 fallback을 둔다.

## 운영 UI 구현 게이트

- ALT 운영 기능은 먼저 화면 없이 CLI, terminal output, YAML scenario, log, test fixture처럼 headless 경로로 구성과 결과를 검증한다.
- Flutter 실화면 구현은 해당 기능의 API/worker/domain 경계와 headless 검증 경로가 먼저 안정화된 뒤에 시작한다.
- 운영 화면 구현 Milestone은 화면 wireframe 또는 동등한 화면 정의 산출물이 준비되고 사용자 승인 기준이 문서화되어야 `구현 잠금`을 해제할 수 있다.
- wireframe 없이 agent가 임의로 dashboard depth, navigation, card layout, chart, form 흐름을 확정하지 않는다.
- Flutter 작업 중 화면 구현이 아닌 app shell, provider boundary, generated contract 연결, headless smoke support는 위 게이트를 깨는 실화면 구현으로 보지 않는다.

## 도메인 매핑

| 경로 패턴 | 도메인 | rules.md |
|----------|--------|----------|
| `packages/domain/**` | domain-model | `agent-ops/rules/project/domain/domain-model/rules.md` |
| `packages/contracts/**` | contracts | `agent-ops/rules/project/domain/contracts/rules.md` |
| `services/api/**` | api | `agent-ops/rules/project/domain/api/rules.md` |
| `services/worker/**` | worker | `agent-ops/rules/project/domain/worker/rules.md` |
| `apps/client/**` | client | `agent-ops/rules/project/domain/client/rules.md` |
| `apps/cli/**`, `bin/**`, `deployments/local/**`, `agent-test/local/**`, `go.work`, `go.work.sum`, `.gitignore` | operations | `agent-ops/rules/project/domain/operations/rules.md` |

## 검증 명령

- 전체 테스트: `bin/test`
- 전체 lint/analyze: `bin/lint`
- 전체 build: `bin/build`
- 로컬 실행 안내: `bin/dev`

## 스킬 라우팅

현재 프로젝트 전용 skill은 만들지 않는다. 반복 작업이 안정되면 `agent-ops/skills/project/` 아래에 추가한다.