trex-core/docs/project-structure.md

Trex Core Project Structure

• Baseline Mode: mixed
• Baseline Seed: .stage-pilot/bootstrap/baseline.yaml
• Status: draft
• Owner: project maintainers
• Last Updated (KST): 2026-06-03
• Source Discovery / Batch: bootstrap-baseline (pre-Discovery, 3-phase lifecycle 밖의 bootstrap 산출물)

Project Summary

• trex 제품군의 공용 베이스로, 첫 도메인으로 trex-orbit 의 일일 거래 슬롯 생명주기(slot) 순수 도메인을 storage-agnostic 하게 이식한 코어다.

Primary Domain

• 자동매매 일일 거래 슬롯 생명주기 도메인 (equity trading slot lifecycle)

Tech Stack

• Python >=3.12
• pyproject.toml 기반 패키지 (setuptools)
• pytest (단위 테스트)
• ruff (린트)
• storage-agnostic 순수 도메인 (현재 in-memory repository, PostgreSQL/psycopg 는 향후 영속화 단계에서 도입 예정)

Primary Runtime

• Type: daemon (HTTP API) + library (slot 도메인)
• Entry Points:
  • trex-core-daemon (console_script → trex_core.runtime.daemon:main) :: 슬롯 코어 데몬 — migrate+preallocate lifecycle 후 FastAPI/uvicorn 으로 /v1 API 서빙 (BAT-002)
  • HTTP /v1 :: 매수·매도 전략 데몬용 intent 제출/조회 경계 (docs/interface-contract.md)
  • SlotService / SlotRepository (Protocol) :: in-process 도메인 서비스 + 저장소 경계(라이브러리 사용)

Purpose

• This document is the current approved repository and package structure baseline.
• It is a cross-cutting reference document for Discovery, REQ, Batch Design, Batch Verification, and implementation updates.

Scope

• Covers the top-level repository layout and package/module boundaries.
• Does not duplicate detailed business rules, acceptance criteria, or implementation-only function signatures.

Top-Level Structure

.
├── .github/                      # Copilot instructions + StagePilot skill entrypoints
│   ├── instructions/
│   └── skills/
├── .stage-pilot/                 # StagePilot 도구/템플릿/부트스트랩 seed
│   ├── bootstrap/
│   │   └── baseline.yaml
│   └── templates/
├── docs/                         # SDLC baseline 문서 + active index
│   ├── batches/index.md
│   ├── discovery/index.md
│   ├── releases/index.md
│   ├── srs/index.md
│   ├── data-model.md
│   ├── interface-contract.md
│   ├── project-structure.md
│   └── runtime-flows.md
├── CLAUDE.md                     # SDLC governance instructions
├── pyproject.toml                # 패키지 메타(배포명 trex-core) + console_scripts(trex-core-daemon) + deps
├── trex_core/
│   ├── __init__.py
│   ├── domain/slot/              # slot 순수 도메인 (BAT-001, 무의존)
│   │   ├── __init__.py · state.py · models.py(+EXPECTED_SLOT_FIELDS) · errors.py
│   │   ├── repository.py(Protocol) · service.py · in_memory_repository.py
│   ├── application/              # 유스케이스 (BAT-002, BAT-004)
│   │   ├── ports.py              # IntentStore Protocol
│   │   ├── intents.py            # IntentService / BuyIntent / SellIntent / IntentDecision
│   │   ├── broker_port.py        # BrokerPort + OrderRequest/OrderAck/FillStatus (BAT-004)
│   │   └── execution.py          # ExecutionService (claim·dispatch·poll·transition·reconcile)
│   ├── adapters/                 # 인프라 어댑터 (BAT-002, BAT-004)
│   │   ├── api/                  # FastAPI: app.py(create_app /v1) · schemas.py
│   │   ├── broker/               # paper.py(결정적 async 더블) · kis.py(KIS Open API)  (BAT-004)
│   │   └── persistence/          # postgresql.py · in_memory_intent_store.py · migrate.py · sql/
│   └── runtime/                  # 데몬 (BAT-002, BAT-004)
│       ├── config.py             # DaemonConfig + KISConfig(env, broker 선택/게이팅)
│       └── daemon.py             # build_app + lifespan(migrate/preallocate/reconcile/execution 루프)
└── tests/
    ├── domain/slot/              # test_state / test_service / test_contract
    ├── application/              # test_intent_concurrency · test_execution (집행 lifecycle)
    └── adapters/{api,broker,persistence}/  # API · paper/KIS · PG repo/migration/drift

참고: domain(BAT-001)은 무의존 코어. application/adapters/runtime 은 BAT-002 에서 추가, BAT-004 에서 broker/execution 레이어 확장. 웹/DB/브로커 의존(fastapi/uvicorn/psycopg/httpx)은 adapters/runtime 에만 격리(NFR). 브로커 주문은 BrokerPort 단일 세션(불변식 B), 슬롯 쓰기는 SlotService 단일 writer(불변식 A).

Package / Module Responsibilities

• trex_core/domain/slot/
  • 슬롯 생명주기 순수 도메인. 6 상태 머신(state.py), 데이터 모델 + 컬럼 계약(models.py, EXPECTED_SLOT_FIELDS 포함), 예외(errors.py), 저장소 계약(repository.py Protocol), 도메인 서비스(service.py), in-memory 구현(in_memory_repository.py).
  • 외부 의존 0 — stdlib 와 패키지 내부 참조만 사용(정적 import 스윕으로 확인됨).
• tests/domain/slot/
  • 상태머신/서비스 단위 테스트(test_state, test_service) + 컬럼 계약 가드(test_contract). InMemorySlotRepository 기반으로 실제 DB 없이 검증.
• docs/
  • SDLC baseline(구조/흐름/인터페이스/데이터 모델) 및 active index(discovery/srs/batches/releases).
• pyproject.toml
  • 패키지 메타데이터(배포명 trex-core, requires-python >=3.12), dev 의존성(pytest/ruff), pytest/ruff 설정.

Dependency Rules

• 순수 도메인(trex_core/domain/slot/)은 저장소 구현, 브로커, 네트워크, CLI 등 인프라에 직접 의존하지 않는다.
• 저장소 접근은 오직 SlotRepository Protocol 을 통해서만 이뤄지고 구현체는 주입된다.
• 인프라(향후 PostgreSQL 구현, CLI, config)는 도메인을 의존할 수 있으나 그 역은 금지한다.

Shared Boundaries

• SlotRepository Protocol 이 도메인 ↔ 저장소 사이의 단일 경계다.
• SLOT_ADVISORY_LOCK_ID 상수가 모든 상태 변경 직렬화의 공유 기준점이다.

Current Gaps / Planned Changes

• 영속화 구현체(PostgreSQL repository)와 SQL 스키마/마이그레이션은 이번 범위 밖 — 향후 도입.
• CLI / 설정(config) 표면 없음(trex-orbit 의 trex slot CLI 미이식).
• 패키지 네임스페이스는 trex_core.domain.slot 으로 확정(dcy-001 OQ-1, 배포명 trex-core).
• 컬럼 계약 드리프트는 EXPECTED_SLOT_FIELDS + test_contract.py 로 강제(DB-side 검사는 영속화 반복 인계).

Update Triggers

• Update this document when package boundaries change.
• Update this document when new top-level runtime or domain modules are added.
• Update this document when a batch changes the approved structure baseline.

Change Log

• 2026-06-03 :: bootstrap-baseline 으로 초기 구조 baseline 생성(mixed: trex-orbit 코드 관찰 + 이관 계획 선언).
• 2026-06-03 :: dcy-001 OQ-1 결정 반영 — planned 네임스페이스를 app/ → trex_core/ 로 정정(배포명 trex-core).
• 2026-06-03 :: BAT-001 이식 완료 반영 — trex_core/·tests/·pyproject.toml planned→실제 정합(REQ-004).
• 2026-06-03 :: BAT-002 — application/adapters/runtime 레이어(데몬+HTTP API+PostgreSQL) 추가, Primary Runtime=daemon+library(REQ-005~009).
• 2026-06-04 :: BAT-004 — 브로커 집행 레이어 반영(BrokerPort/paper·KIS 어댑터, execution 루프, broker_order_id 실행큐·멱등, reconciliation) (REQ-011~015).