quantbench/system-specs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: 프로젝트 개요 및 컴포넌트별 명세, 로드맵 등 문서 추가

Browse Source
This commit is contained in:
Jongheon Kim
2026-01-11 21:01:34 +09:00
parent 8553f586c9
commit 6c6ca894cf
23 changed files with 8388 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

616
diagram.md Normal file
View File

@@ -0,0 +1,616 @@
# QuantBench System Architecture - Mermaid Diagrams
## 1. 전체 시스템 아키텍처 (All Phases)
```mermaid
graph TB
subgraph "User Layer"
UI[User Interface<br/>Web/Mobile/Desktop]
end
subgraph "API Layer"
Gateway[API Gateway<br/>Authentication & Rate Limiting]
end
subgraph "Phase 1 - Core Components"
Balance[balance<br/>계좌 관리]
Mgmt[mgmt<br/>컨테이너 관리]
Strategy[strategy<br/>전략 관리]
Scheduler[scheduler<br/>실행 스케줄러]
Risk[risk<br/>리스크 관리]
Data[data<br/>데이터 관리]
end
subgraph "Phase 2 - Production Ready"
Analytics[analytics<br/>성과 분석]
Monitor[monitor<br/>모니터링 & 알림]
end
subgraph "Phase 3 - Enterprise Grade"
Audit[audit<br/>감사 로깅]
Simulation[simulation<br/>시뮬레이션]
end
subgraph "Infrastructure"
MQ[Message Queue<br/>Kafka/RabbitMQ]
DB[(Database<br/>PostgreSQL)]
Cache[(Cache<br/>Redis)]
Storage[(Object Storage<br/>S3)]
end
subgraph "External Systems"
Broker1[한국투자증권 API]
Broker2[삼성증권 API]
Broker3[키움증권 API]
DataProvider[Data Providers<br/>Yahoo/Alpha Vantage]
end
UI --> Gateway
Gateway --> Mgmt
Gateway --> Strategy
Gateway --> Scheduler
Gateway --> Analytics
Gateway --> Monitor
Gateway --> Simulation
Scheduler --> Strategy
Scheduler --> Mgmt
Scheduler --> Risk
Scheduler --> Balance
Strategy --> Data
Strategy --> Risk
Mgmt --> Balance
Mgmt --> Risk
Analytics --> Mgmt
Analytics --> Data
Monitor --> Mgmt
Monitor --> Balance
Monitor --> Scheduler
Simulation --> Strategy
Simulation --> Data
Simulation --> Risk
Audit -.-> Mgmt
Audit -.-> Strategy
Audit -.-> Scheduler
Audit -.-> Balance
Balance --> Broker1
Balance --> Broker2
Balance --> Broker3
Data --> DataProvider
Data --> Broker1
Mgmt --> DB
Strategy --> DB
Analytics --> DB
Audit --> DB
Data --> Cache
Monitor --> Cache
Analytics --> Storage
Audit --> Storage
Scheduler --> MQ
Monitor --> MQ
style Balance fill:#e1f5ff
style Mgmt fill:#e1f5ff
style Strategy fill:#e1f5ff
style Scheduler fill:#e1f5ff
style Risk fill:#e1f5ff
style Data fill:#e1f5ff
style Analytics fill:#fff4e1
style Monitor fill:#fff4e1
style Audit fill:#f0e1ff
style Simulation fill:#f0e1ff
```
## 2. Phase 1 컴포넌트 관계도
```mermaid
graph LR
subgraph "Phase 1: MVP"
subgraph "Core Trading"
Mgmt[mgmt<br/>컨테이너 관리]
Strategy[strategy<br/>전략 엔진]
Scheduler[scheduler<br/>스케줄러]
end
subgraph "Safety & Control"
Risk[risk<br/>리스크 관리]
Data[data<br/>데이터 수집]
end
subgraph "Broker Integration"
Balance[balance<br/>계좌 연동]
end
end
Scheduler -->|1. 트리거| Strategy
Strategy -->|2. 신호 생성| Risk
Risk -->|3. 검증 통과| Scheduler
Scheduler -->|4. 주문 생성| Balance
Balance -->|5. 체결 결과| Mgmt
Strategy -->|시세 조회| Data
Risk -->|리스크 데이터| Data
Mgmt -->|자산 할당| Balance
style Mgmt fill:#4CAF50,color:#fff
style Strategy fill:#2196F3,color:#fff
style Scheduler fill:#FF9800,color:#fff
style Risk fill:#F44336,color:#fff
style Data fill:#9C27B0,color:#fff
style Balance fill:#00BCD4,color:#fff
```
## 3. 전체 Phase별 구성
```mermaid
graph TB
subgraph "Phase 3: Enterprise Grade"
P3_1[audit<br/>감사 추적]
P3_2[simulation<br/>Paper Trading]
end
subgraph "Phase 2: Production Ready"
P2_1[analytics<br/>성과 분석]
P2_2[monitor<br/>모니터링]
end
subgraph "Phase 1: MVP"
P1_1[balance<br/>계좌 관리]
P1_2[mgmt<br/>컨테이너]
P1_3[strategy<br/>전략]
P1_4[scheduler<br/>스케줄러]
P1_5[risk<br/>리스크]
P1_6[data<br/>데이터]
end
P1_1 --> P2_1
P1_2 --> P2_1
P1_3 --> P2_1
P1_6 --> P2_1
P1_1 --> P2_2
P1_2 --> P2_2
P1_4 --> P2_2
P2_1 --> P3_1
P1_4 --> P3_1
P1_1 --> P3_1
P1_3 --> P3_2
P1_6 --> P3_2
P1_5 --> P3_2
style P1_1 fill:#e3f2fd
style P1_2 fill:#e3f2fd
style P1_3 fill:#e3f2fd
style P1_4 fill:#e3f2fd
style P1_5 fill:#e3f2fd
style P1_6 fill:#e3f2fd
style P2_1 fill:#fff9c4
style P2_2 fill:#fff9c4
style P3_1 fill:#f3e5f5
style P3_2 fill:#f3e5f5
```
## 4. 전략 실행 워크플로우 (Sequence Diagram)
```mermaid
sequenceDiagram
participant S as Scheduler
participant M as Mgmt
participant ST as Strategy
participant D as Data
participant R as Risk
participant B as Balance
participant A as Analytics
participant MO as Monitor
Note over S: 스케줄 트리거 발생
S->>M: 1. 컨테이너 정보 조회
M-->>S: 컨테이너 설정 & 현재 포지션
S->>ST: 2. 전략 실행 요청
ST->>D: 2.1 시장 데이터 조회
D-->>ST: 최신 시세 데이터
ST->>ST: 2.2 신호 생성
ST-->>S: 매매 신호 반환
S->>R: 3. 리스크 체크
R->>R: 3.1 포지션 사이즈 검증
R->>R: 3.2 VaR 계산
R->>R: 3.3 한도 확인
alt 리스크 체크 실패
R-->>S: 검증 실패
S->>MO: 알림 발송
MO-->>S: 알림 완료
Note over S: 실행 중단
else 리스크 체크 통과
R-->>S: 검증 통과
alt 승인 필요 모드
S->>S: 승인 요청 생성
S->>MO: 사용자에게 알림
Note over S: 사용자 승인 대기
S->>S: 승인 완료
end
S->>B: 4. 주문 제출
B->>B: 4.1 증권사 API 호출
B-->>S: 주문 접수 완료
Note over B: 체결 대기...
B->>B: 4.2 체결 확인
B->>M: 5. 포지션 업데이트
M->>M: 5.1 컨테이너 밸런스 갱신
M->>A: 6. 성과 계산 트리거
A->>A: 6.1 수익률 계산
A->>A: 6.2 리스크 지표 갱신
A->>MO: 7. 메트릭 업데이트
MO->>MO: 7.1 대시보드 갱신
MO->>MO: 7.2 이상 탐지
alt 이상 탐지 시
MO->>MO: 알림 발송
end
S->>S: 8. 실행 완료 기록
end
```
## 5. 리스크 관리 플로우
```mermaid
graph TB
Start([주문 요청]) --> GetPosition[현재 포지션 조회]
GetPosition --> CalcNewPosition[신규 포지션 계산]
CalcNewPosition --> CheckBalance{잔고 충분?}
CheckBalance -->|No| Reject1[주문 거부:<br/>잔고 부족]
CheckBalance -->|Yes| CheckSize
CheckSize{포지션 사이즈<br/>한도 내?}
CheckSize -->|No| Reject2[주문 거부:<br/>사이즈 초과]
CheckSize -->|Yes| CheckConcentration
CheckConcentration{집중도<br/>한도 내?}
CheckConcentration -->|No| Reject3[주문 거부:<br/>집중도 초과]
CheckConcentration -->|Yes| CalcVaR
CalcVaR[VaR 계산]
CalcVaR --> CheckVaR{VaR<br/>한도 내?}
CheckVaR -->|No| Warning1[경고 발생<br/>계속 진행]
CheckVaR -->|Yes| CheckDrawdown
Warning1 --> CheckDrawdown
CheckDrawdown{최대 낙폭<br/>한도 내?}
CheckDrawdown -->|No| Reject4[주문 거부:<br/>MDD 초과]
CheckDrawdown -->|Yes| CheckLeverage
CheckLeverage{레버리지<br/>한도 내?}
CheckLeverage -->|No| Reject5[주문 거부:<br/>레버리지 초과]
CheckLeverage -->|Yes| Approve
Approve([검증 통과:<br/>주문 실행])
Reject1 --> Log[리스크 로그 기록]
Reject2 --> Log
Reject3 --> Log
Reject4 --> Log
Reject5 --> Log
Approve --> ExecuteOrder[주문 제출]
ExecuteOrder --> Monitor[실시간 모니터링]
Monitor --> CheckStop{손절/익절<br/>조건 충족?}
CheckStop -->|Yes| AutoClose[자동 청산]
CheckStop -->|No| Monitor
style Start fill:#4CAF50,color:#fff
style Approve fill:#4CAF50,color:#fff
style Reject1 fill:#F44336,color:#fff
style Reject2 fill:#F44336,color:#fff
style Reject3 fill:#F44336,color:#fff
style Reject4 fill:#F44336,color:#fff
style Reject5 fill:#F44336,color:#fff
style Warning1 fill:#FF9800,color:#fff
```
## 6. 데이터 흐름도
```mermaid
graph LR
subgraph "External Sources"
Broker[증권사 API]
YahooAPI[Yahoo Finance]
AlphaAPI[Alpha Vantage]
end
subgraph "Data Collection"
Collector[Data Collector]
RealTime[Real-time Stream]
Historical[Historical Fetch]
end
subgraph "Data Processing"
Validator[Data Validator]
Adjuster[Corporate Action Adjuster]
QualityCheck[Quality Check]
end
subgraph "Storage"
Cache[(Redis Cache<br/>실시간 시세)]
TimeSeries[(Time Series DB<br/>과거 데이터)]
Metadata[(Metadata DB<br/>종목 정보)]
end
subgraph "Consumers"
Strategy[Strategy Engine]
Backtest[Backtest Engine]
Analytics[Analytics]
Monitor[Monitor]
end
Broker --> RealTime
YahooAPI --> Historical
AlphaAPI --> Historical
RealTime --> Collector
Historical --> Collector
Collector --> Validator
Validator --> QualityCheck
QualityCheck -->|Pass| Adjuster
QualityCheck -->|Fail| Alert[Quality Alert]
Adjuster --> Cache
Adjuster --> TimeSeries
Adjuster --> Metadata
Cache --> Strategy
Cache --> Monitor
TimeSeries --> Backtest
TimeSeries --> Analytics
Metadata --> Strategy
style Cache fill:#FF6B6B,color:#fff
style TimeSeries fill:#4ECDC4,color:#fff
style Metadata fill:#45B7D1,color:#fff
```
## 7. 컨테이너 생명주기
```mermaid
stateDiagram-v2
[*] --> Created: createContainer()
Created --> Active: activate()
Created --> [*]: delete()
Active --> Running: scheduler trigger
Active --> Paused: pause()
Active --> [*]: delete()
Running --> Active: execution complete
Running --> Error: execution failed
Running --> Paused: emergency stop
Paused --> Active: resume()
Paused --> [*]: delete()
Error --> Active: resolve & restart
Error --> Paused: manual intervention
Error --> [*]: delete()
state Running {
[*] --> GenerateSignals
GenerateSignals --> RiskCheck
RiskCheck --> PlaceOrders: pass
RiskCheck --> [*]: fail
PlaceOrders --> AwaitFill
AwaitFill --> UpdatePosition
UpdatePosition --> [*]
}
```
## 8. 승인 워크플로우
```mermaid
graph TB
Trigger[스케줄 트리거] --> GenerateSignals[신호 생성]
GenerateSignals --> RiskCheck[리스크 체크]
RiskCheck --> CheckMode{실행 모드}
CheckMode -->|AUTO| AutoExecute[자동 실행]
CheckMode -->|APPROVAL| CreateRequest
CreateRequest[승인 요청 생성]
CreateRequest --> SendNotification[알림 발송]
SendNotification --> WaitApproval[승인 대기]
WaitApproval --> CheckTimeout{타임아웃?}
CheckTimeout -->|Yes| Expired[요청 만료]
CheckTimeout -->|No| WaitApproval
WaitApproval --> UserDecision{사용자 결정}
UserDecision -->|승인| Execute[주문 실행]
UserDecision -->|거부| Rejected[실행 거부]
AutoExecute --> Execute
Execute --> PlaceOrders[주문 제출]
PlaceOrders --> Success{성공?}
Success -->|Yes| NotifySuccess[성공 알림]
Success -->|No| NotifyFail[실패 알림]
Rejected --> LogRejection[거부 로그]
Expired --> LogExpired[만료 로그]
NotifySuccess --> End([완료])
NotifyFail --> End
LogRejection --> End
LogExpired --> End
style Execute fill:#4CAF50,color:#fff
style Rejected fill:#F44336,color:#fff
style Expired fill:#FF9800,color:#fff
style AutoExecute fill:#2196F3,color:#fff
```
## 9. 모니터링 & 알림 시스템
```mermaid
graph TB
subgraph "Data Sources"
Positions[포지션 데이터]
Orders[주문 데이터]
PnL[손익 데이터]
System[시스템 메트릭]
end
subgraph "Monitoring Engine"
Collector[Metrics Collector]
Anomaly[Anomaly Detector]
Health[Health Checker]
Rules[Alert Rules Engine]
end
subgraph "Alert Processing"
Evaluator[Alert Evaluator]
Throttle[Throttle Manager]
Router[Channel Router]
end
subgraph "Notification Channels"
Email[Email]
SMS[SMS]
Push[Push Notification]
Slack[Slack]
end
subgraph "Storage & Dashboard"
Metrics[(Metrics DB)]
Dashboard[Real-time Dashboard]
History[Alert History]
end
Positions --> Collector
Orders --> Collector
PnL --> Collector
System --> Collector
Collector --> Anomaly
Collector --> Health
Collector --> Rules
Collector --> Metrics
Anomaly --> Evaluator
Health --> Evaluator
Rules --> Evaluator
Evaluator --> Throttle
Throttle --> Router
Router --> Email
Router --> SMS
Router --> Push
Router --> Slack
Evaluator --> History
Metrics --> Dashboard
style Anomaly fill:#F44336,color:#fff
style Health fill:#4CAF50,color:#fff
style Rules fill:#FF9800,color:#fff
```
## 10. Simulation 환경 구조
```mermaid
graph TB
subgraph "Real Environment"
RealAccount[실제 계좌]
RealBroker[증권사 API]
RealData[실시간 시세]
end
subgraph "Simulation Environment"
PaperAccount[가상 계좌]
subgraph "Simulation Engine"
OrderSim[주문 시뮬레이터]
FillSim[체결 시뮬레이터]
Slippage[슬리피지 모델]
Commission[수수료 계산]
end
subgraph "Test Scenarios"
Historical[과거 데이터 리플레이]
MonteCarlo[몬테카를로 시뮬레이션]
Stress[스트레스 테스트]
end
end
subgraph "Shared Components"
Strategy[전략 엔진]
Risk[리스크 관리]
Analytics[성과 분석]
end
RealData --> Historical
RealData --> OrderSim
Strategy --> OrderSim
Strategy --> RealBroker
OrderSim --> FillSim
FillSim --> Slippage
Slippage --> Commission
Commission --> PaperAccount
Historical --> MonteCarlo
Historical --> Stress
PaperAccount --> Analytics
RealAccount --> Analytics
Risk --> OrderSim
Risk --> RealBroker
Analytics --> Validation{검증 통과?}
Validation -->|Yes| Promote[실계좌 전환]
Validation -->|No| Refine[전략 개선]
Promote --> RealAccount
Refine --> Strategy
style PaperAccount fill:#FFF9C4
style RealAccount fill:#C8E6C9
style Validation fill:#FF9800,color:#fff
```