toki
a8a0f691cf
- Add socket handler and server implementations for real-time communication - Add Mattermost integration (auth service, push client, plugin client) - Add Mattermost push host integration tests - Update Flutter client app with new app structure and bootstrap - Update Android build configurations and add Google Services config - Add asset keep file for Flutter client - Update agent-roadmap with api-centered-proto-socket-rail milestone - Update agent-task with planning and code review documents for all groups - Update domain rules for api, client, worker and project rules
77 lines
5 KiB
Markdown
77 lines
5 KiB
Markdown
# 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을 둔다.
|
|
|
|
## 도메인 매핑
|
|
|
|
| 경로 패턴 | 도메인 | 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/**`, `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/` 아래에 추가한다.
|