toki/alt

toki c4a457c5c4 docs(agent-ops): domain rule과 로드맵을 operator reliability refactor에 맞게 갱신한다

API domain에 workerclient proxy와 handler responsibility를 추가하고,
worker domain에 backtest engine, storage, provider, socket surface를 명시한다.
Client domain에 socket integration과 push integration 경계를 보강한다.
Operations domain에 agent-test/local과 bin 명령어를 포함하며,
operations domain table에 agent-test/local 경계를 추가한다.

로드맵에 Operator Runtime Reliability Refactor Milestone를 추가하고
현재 활성 Milestone으로 설정하여 Flutter Operator Console 전에
선행할 작업으로 변경한다.

2026-05-31 06:53:24 +09:00

5.8 KiB

Raw Blame History

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/ 아래에 추가한다.

5.8 KiB Raw Blame History