Bithumb/docs/reference/ARCHITECTURE.md

DeepCoin 아키텍처 — Ground Truth · Simulation · Operations

프로젝트는 세 축만 사용합니다. 예전 Phase A/B/C·dry-run·paper 모의 체결은 제거되었습니다.

flowchart TB
    subgraph data [공통 데이터]
        DL[01_download]
        DB[(coins.db)]
        DL --> DB
    end

    subgraph gt [Ground Truth]
        GT02[02_ground_truth]
        GT03[03 분석·프로필]
        GT05[05_chart_truth]
        DB --> GT02
        GT02 --> GJSON[ground_truth_trades.json]
        GT03 --> GJSON
        GJSON --> GT05
    end

    subgraph sim [Simulation]
        M04[04_match_rules]
        S04[04_simulation_report]
        GJSON --> M04
        DB --> M04
        M04 --> MR[matched_rules.json]
        MR --> S04
        S04 --> SR[simulation_report.*]
    end

    subgraph ops [Operations]
        V06[06_verify_live]
        E06[06_execute_live]
        MR --> E06
        SR --> V06
        E06 --> BT[빗썸 API]
    end

---

1. Ground Truth (정답)

Plan — 목적

• 벤치마크 매수·매도 타점·leg·비중 (운영 목표 수익의 상한 참고).
• 미래 데이터 허용: ZigZag·피벗은 사후 라벨링 (ground_truth.py).
• 시뮬·운영 규칙의 교사 신호가 아님 (oracle 직접 매매 금지).

Do — 실행

순서	스크립트	산출
(선행)	01_download.py	data/coins.db (3m~일봉 + 주·월봉)
1	02_ground_truth.py	data/ground_truth/ground_truth_trades.json
2	03_analyze_enrich.py	docs/03_analysis/latest/* (10TF 지표)
3	03_analyze_trades.py	general_analysis_trades.csv (GT 타점 스냅샷)
4	03_gt_mtf_profile.py	gt_mtf_profile.json (규칙 후보 입력)
5	05_chart_truth.py	docs/02_ground_truth/wld_ground_truth_chart.html

패키지: deepcoin/ground_truth/, deepcoin/analysis/

Check — 핵심 설정

변수	의미
CHART_LOOKBACK_DAYS	GT·스캔 구간 (기본 365)
GT_INITIAL_CASH_KRW	GT 포트폴리오 시뮬 초기 자금 (40만)
GT_*	ZigZag·분할 매수·leg 티어

Act — 갱신 시

GT 파라미터·구간 변경 후 02 → 03 → 05* 순 재실행.

---

2. Simulation (시뮬레이션)

Plan — 목적

• GT 프로필에서 규칙 후보 생성 → 전 구간 발화 스캔 → EV·holdout 검증.
• 과거 데이터만 사용 (GT_SIGNAL_CAUSAL=1, enrich_scan_frame_gt_signals(causal=True)).
• 초기 자금 40만 원, 현금 있을 때만 매수, 보유 있을 때만 매도 (gt_allocation / HybridSimPortfolio).

Do — 실행

순서	스크립트	산출
1	04_match_rules.py	matched_rules.json, fire_outcomes.csv
2	04_simulation_report.py	simulation_report.json/html, Go/No-Go
(선택)	04_hybrid_dd_calibrate.py	hybrid_dd_calibration.json
(선택)	04_causal_gt_calibrate.py	causal_gt_calibration.json

패키지: deepcoin/matching/

Check — 운영 규칙·배분

항목	값
monitor_rules	buy_compound_tight, sell_mtf_cross_all_tf (주봉 w1 조건 포함 가능)
권장 primary	sim_causal_hybrid (hybrid DD tier, enhanced=False)
배포 금지	sim_tier_enhanced (conviction)
Go/No-Go	holdout EV, MDD, fee stress — SIMULATION.md

Act — 재검증

데이터·GT·GENERAL_ANALYSIS_INTERVALS 변경 시 04_match → 04_simulation 재실행.
운영 전 simulation_report.html 에서 hybrid Go/No-Go 확인.

---

3. Operations (운영)

Plan — 목적

• 시뮬과 동일 규칙·동일 hybrid 배분으로 빗썸 실주문.
• LIVE_TRADING_ENABLED=1 필수. dry-run·paper 없음.

Do — 실행

순서	스크립트	역할
(선행)	00_sync_ops.py	운영 전 봉 동기화
1	06_verify_live.py	설정·규칙·한도·tier 점검
2	check_balance.py	빗썸 KRW·보유 확인
3	06_execute_live.py	실거래 루프 (--once 1회 테스트)
(선택)	05_run_monitor.py	알림만 (주문 없음)

패키지: deepcoin/ops/live_trader.py, hybrid_sim_execution.py

Check — 제약 (시뮬과 동일)

제약	구현
초기 자금	GT_INITIAL_CASH_KRW=400000 (배분 기준)
매수	가용 현금·수수료, LIVE_DAILY_KRW_MAX, EV/WF 통과 매수만
매도	보유 수량, plan_live_hit → sell_qty
이력	LIVE_HYBRID_BOOTSTRAP_FIRES=1 → fire_outcomes monitor 발화 + 운영 체결분
인과	발화 시점까지 OHLC·지표만 (live_eval + causal GT signals)

Act — Kill switch

1. 06_execute_live 프로세스 중지
2. 빗썸 앱 수동 청산
3. 필요 시 01~04 재실행 후 규칙·시뮬 재승인

---

스크립트 번호 ↔ 축 (빠른 참조)

축	스크립트
데이터	01_download, 00_sync_ops
GT	02, 03_*, 05_chart_truth
Sim	04_match_rules, 04_simulation_report, 04_*_calibrate
Ops	06_verify_live, 06_execute_live, check_balance, 05_run_monitor
검증	verify_env.py, test_buy_sell_rehearsal.py

---

데이터·미래 사용 정책

축	미래 데이터
Ground Truth	허용 (라벨링·벤치마크)
Simulation	금지 (발화·스캔·배분 tier는 과거 leg·DD만)
Operations	금지 (Simulation과 동일 규칙·엔진)

---

관련 문서

문서	내용
GROUND_TRUTH.md	GT 타점·배분 상세
SIMULATION.md	Go/No-Go·portfolio_compare
LIVE_TRADING.md	06 실거래
OPERATIONS.md	일상 루틴
RISK.md	한도·Kill switch
DEPLOYMENT_CHECKLIST.md	기동 체크리스트