593 lines
15 KiB
Markdown
593 lines
15 KiB
Markdown
# QuantBench 시스템 아키텍처
|
|
|
|
## 1. 전체 시스템 구조
|
|
|
|
```mermaid
|
|
graph TB
|
|
subgraph "사용자 레이어"
|
|
UI[사용자 인터페이스<br/>Web/Mobile/Desktop]
|
|
end
|
|
|
|
subgraph "API 레이어"
|
|
Gateway[API Gateway<br/>인증 & Rate Limiting]
|
|
end
|
|
|
|
subgraph "Phase 1: 핵심 컴포넌트"
|
|
Balance[balance<br/>계좌 관리]
|
|
Mgmt[mgmt<br/>컨테이너 관리]
|
|
Strategy[strategy<br/>전략 관리]
|
|
Scheduler[scheduler<br/>실행 스케줄러]
|
|
Risk[risk<br/>리스크 관리]
|
|
Data[data<br/>데이터 관리]
|
|
end
|
|
|
|
subgraph "Phase 2: 프로덕션"
|
|
Analytics[analytics<br/>성과 분석]
|
|
Monitor[monitor<br/>모니터링 & 알림]
|
|
end
|
|
|
|
subgraph "Phase 3: 엔터프라이즈"
|
|
Audit[audit<br/>감사 로깅]
|
|
Simulation[simulation<br/>시뮬레이션]
|
|
end
|
|
|
|
subgraph "인프라"
|
|
MQ[Message Queue<br/>Kafka/RabbitMQ]
|
|
DB[(Database<br/>PostgreSQL)]
|
|
Cache[(Cache<br/>Redis)]
|
|
Storage[(Object Storage<br/>S3)]
|
|
end
|
|
|
|
subgraph "외부 시스템"
|
|
Broker1[한국투자증권 API]
|
|
Broker2[삼성증권 API]
|
|
Broker3[키움증권 API]
|
|
DataProvider[데이터 제공자<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. 컴포넌트 개요
|
|
|
|
### 2.1 Phase 1: 핵심 컴포넌트
|
|
|
|
| 컴포넌트 | 책임 | 주요 기능 |
|
|
|---------|------|----------|
|
|
| **balance** | 증권사 API 통합 및 계좌 자산 관리 | 계좌 연동, 잔고 조회, 시세 조회, 주문 처리 |
|
|
| **mgmt** | 가상 자산 컨테이너 생성 및 운영 관리 | 컨테이너 생명주기, 자산 격리, 밸런스 조정 |
|
|
| **strategy** | 투자 전략 구현, 백테스트, 버전 관리 | 전략 등록, 신호 생성, 백테스트, 파라미터 관리 |
|
|
| **scheduler** | 전략 실행 자동화 및 리밸런싱 관리 | 스케줄 관리, 실행 트리거, 승인 워크플로우 |
|
|
| **risk** | 포지션 리스크 통제 및 사전 주문 검증 | 주문 검증, 리스크 모니터링, 손절/익절 |
|
|
| **data** | 시계열 데이터 수집, 저장, 제공 | 데이터 수집, 품질 관리, 데이터 제공 |
|
|
|
|
### 2.2 Phase 2: 프로덕션 컴포넌트
|
|
|
|
| 컴포넌트 | 책임 | 주요 기능 |
|
|
|---------|------|----------|
|
|
| **analytics** | 실거래 성과 측정 및 리포팅 | 성과 측정, 귀속 분석, 거래 분석, 리포트 생성 |
|
|
| **monitor** | 시스템 상태 감시 및 이상 탐지 | 헬스 체크, 이상 탐지, 알림 관리, 대시보드 |
|
|
|
|
### 2.3 Phase 3: 엔터프라이즈 컴포넌트
|
|
|
|
| 컴포넌트 | 책임 | 주요 기능 |
|
|
|---------|------|----------|
|
|
| **audit** | 불변 감사 로그 및 규제 리포팅 | 감사 로그, 변경 추적, 규제 리포팅, 무결성 검증 |
|
|
| **simulation** | 실전 배포 전 안전한 테스트 환경 제공 | Paper Trading, 시뮬레이션, 파라미터 최적화 |
|
|
|
|
## 3. 컴포넌트 상호작용
|
|
|
|
### 3.1 Phase 1 컴포넌트 관계도
|
|
|
|
```mermaid
|
|
graph LR
|
|
subgraph "Phase 1: MVP"
|
|
subgraph "핵심 거래"
|
|
Mgmt[mgmt<br/>컨테이너 관리]
|
|
Strategy[strategy<br/>전략 엔진]
|
|
Scheduler[scheduler<br/>스케줄러]
|
|
end
|
|
|
|
subgraph "안전성 & 통제"
|
|
Risk[risk<br/>리스크 관리]
|
|
Data[data<br/>데이터 수집]
|
|
end
|
|
|
|
subgraph "증권사 연동"
|
|
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.2 Phase별 의존성
|
|
|
|
```mermaid
|
|
graph TB
|
|
subgraph "Phase 3: Enterprise"
|
|
P3_1[audit<br/>감사]
|
|
P3_2[simulation<br/>시뮬레이션]
|
|
end
|
|
|
|
subgraph "Phase 2: Production"
|
|
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. 데이터 흐름
|
|
|
|
### 4.1 시장 데이터 흐름
|
|
|
|
```mermaid
|
|
graph LR
|
|
subgraph "외부 소스"
|
|
Broker[증권사 API]
|
|
Yahoo[Yahoo Finance]
|
|
Alpha[Alpha Vantage]
|
|
end
|
|
|
|
subgraph "데이터 수집"
|
|
Collector[Data Collector]
|
|
RealTime[실시간 스트림]
|
|
Historical[과거 데이터 수집]
|
|
end
|
|
|
|
subgraph "데이터 처리"
|
|
Validator[데이터 검증]
|
|
Adjuster[조정 처리]
|
|
QualityCheck[품질 체크]
|
|
end
|
|
|
|
subgraph "저장소"
|
|
Cache[(Redis<br/>실시간)]
|
|
TimeSeries[(TimescaleDB<br/>과거)]
|
|
Metadata[(Metadata<br/>종목 정보)]
|
|
end
|
|
|
|
subgraph "소비자"
|
|
Strategy[전략 엔진]
|
|
Backtest[백테스트]
|
|
Analytics[분석]
|
|
Monitor[모니터]
|
|
end
|
|
|
|
Broker --> RealTime
|
|
Yahoo --> Historical
|
|
Alpha --> Historical
|
|
|
|
RealTime --> Collector
|
|
Historical --> Collector
|
|
|
|
Collector --> Validator
|
|
Validator --> QualityCheck
|
|
QualityCheck -->|통과| Adjuster
|
|
QualityCheck -->|실패| 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
|
|
```
|
|
|
|
### 4.2 주문 실행 흐름
|
|
|
|
```mermaid
|
|
graph TB
|
|
Start([스케줄 트리거]) --> GetContainer[컨테이너 정보 조회]
|
|
GetContainer --> GenerateSignals[신호 생성]
|
|
GenerateSignals --> GetMarketData[시장 데이터 조회]
|
|
GetMarketData --> Calculate[매매 신호 계산]
|
|
|
|
Calculate --> RiskCheck[리스크 검증]
|
|
|
|
RiskCheck --> CheckResult{검증 결과}
|
|
CheckResult -->|실패| SendAlert[실패 알림]
|
|
CheckResult -->|통과| CheckMode{실행 모드}
|
|
|
|
CheckMode -->|AUTO| ExecuteOrder
|
|
CheckMode -->|APPROVAL| RequestApproval[승인 요청]
|
|
RequestApproval --> WaitApproval[승인 대기]
|
|
WaitApproval --> ExecuteOrder[주문 실행]
|
|
|
|
ExecuteOrder --> SubmitToBroker[증권사에 주문 제출]
|
|
SubmitToBroker --> WaitFill[체결 대기]
|
|
WaitFill --> UpdatePosition[포지션 업데이트]
|
|
UpdatePosition --> Reconcile[밸런스 조정]
|
|
Reconcile --> CalcPerformance[성과 계산]
|
|
CalcPerformance --> CheckAnomaly[이상 탐지]
|
|
CheckAnomaly --> End([완료])
|
|
|
|
SendAlert --> End
|
|
|
|
style RiskCheck fill:#f44336,color:#fff
|
|
style ExecuteOrder fill:#4caf50,color:#fff
|
|
style CheckAnomaly fill:#ff9800,color:#fff
|
|
```
|
|
|
|
## 5. 인프라 아키텍처
|
|
|
|
### 5.1 배포 구조
|
|
|
|
```mermaid
|
|
graph TB
|
|
subgraph "로드 밸런서"
|
|
LB[Load Balancer<br/>Nginx/ALB]
|
|
end
|
|
|
|
subgraph "애플리케이션 레이어"
|
|
API1[API Gateway 1]
|
|
API2[API Gateway 2]
|
|
|
|
Worker1[Worker 1<br/>scheduler/strategy]
|
|
Worker2[Worker 2<br/>analytics]
|
|
end
|
|
|
|
subgraph "데이터 레이어"
|
|
PG_Master[(PostgreSQL<br/>Primary)]
|
|
PG_Replica[(PostgreSQL<br/>Replica)]
|
|
|
|
Redis_Master[(Redis<br/>Primary)]
|
|
Redis_Replica[(Redis<br/>Replica)]
|
|
|
|
TS[(TimescaleDB<br/>시계열)]
|
|
end
|
|
|
|
subgraph "메시지 큐"
|
|
Kafka[Kafka Cluster]
|
|
end
|
|
|
|
subgraph "스토리지"
|
|
S3[(S3<br/>리포트/백업)]
|
|
end
|
|
|
|
subgraph "모니터링"
|
|
Prometheus[Prometheus]
|
|
Grafana[Grafana]
|
|
ELK[ELK Stack]
|
|
end
|
|
|
|
LB --> API1
|
|
LB --> API2
|
|
|
|
API1 --> Worker1
|
|
API2 --> Worker2
|
|
|
|
Worker1 --> PG_Master
|
|
Worker2 --> PG_Replica
|
|
|
|
Worker1 --> Redis_Master
|
|
Worker2 --> Redis_Replica
|
|
|
|
Worker1 --> TS
|
|
Worker2 --> TS
|
|
|
|
Worker1 --> Kafka
|
|
Worker2 --> Kafka
|
|
|
|
Worker1 --> S3
|
|
Worker2 --> S3
|
|
|
|
PG_Master -.->|복제| PG_Replica
|
|
Redis_Master -.->|복제| Redis_Replica
|
|
|
|
API1 --> Prometheus
|
|
Worker1 --> Prometheus
|
|
Prometheus --> Grafana
|
|
|
|
API1 --> ELK
|
|
Worker1 --> ELK
|
|
|
|
style PG_Master fill:#4CAF50,color:#fff
|
|
style Redis_Master fill:#FF6B6B,color:#fff
|
|
style Kafka fill:#FF9800,color:#fff
|
|
```
|
|
|
|
### 5.2 데이터베이스 스키마 분리
|
|
|
|
```mermaid
|
|
graph TB
|
|
subgraph "PostgreSQL"
|
|
subgraph "Core Schema"
|
|
Accounts[accounts<br/>계좌 정보]
|
|
Containers[containers<br/>컨테이너]
|
|
Strategies[strategies<br/>전략]
|
|
Orders[orders<br/>주문]
|
|
Positions[positions<br/>포지션]
|
|
end
|
|
|
|
subgraph "Config Schema"
|
|
RiskLimits[risk_limits<br/>리스크 한도]
|
|
Schedules[schedules<br/>스케줄]
|
|
AlertRules[alert_rules<br/>알림 규칙]
|
|
end
|
|
|
|
subgraph "Analytics Schema"
|
|
Performance[performance<br/>성과 데이터]
|
|
Reports[reports<br/>리포트]
|
|
end
|
|
|
|
subgraph "Audit Schema"
|
|
AuditLogs[audit_logs<br/>감사 로그]
|
|
ChangeLogs[change_logs<br/>변경 이력]
|
|
end
|
|
end
|
|
|
|
subgraph "TimescaleDB"
|
|
PriceBars[price_bars<br/>가격 데이터]
|
|
Metrics[metrics<br/>메트릭]
|
|
Trades[trades<br/>거래 이력]
|
|
end
|
|
|
|
subgraph "Redis"
|
|
RealtimePrices[실시간 시세]
|
|
SessionCache[세션 캐시]
|
|
RateLimits[Rate Limit]
|
|
end
|
|
|
|
Containers --> Accounts
|
|
Strategies --> Containers
|
|
Orders --> Containers
|
|
Positions --> Containers
|
|
|
|
RiskLimits --> Containers
|
|
Schedules --> Containers
|
|
|
|
Performance --> Containers
|
|
Reports --> Performance
|
|
|
|
AuditLogs --> Containers
|
|
ChangeLogs --> Containers
|
|
|
|
style Accounts fill:#e3f2fd
|
|
style Containers fill:#e3f2fd
|
|
style AuditLogs fill:#f3e5f5
|
|
style PriceBars fill:#fff9c4
|
|
```
|
|
|
|
## 6. 보안 아키텍처
|
|
|
|
### 6.1 인증 및 권한
|
|
|
|
```mermaid
|
|
graph LR
|
|
User[사용자] --> Auth[인증 서비스]
|
|
Auth --> JWT[JWT 토큰 발급]
|
|
JWT --> Gateway[API Gateway]
|
|
|
|
Gateway --> RBAC[권한 체크]
|
|
RBAC -->|관리자| AdminAPI[관리 API]
|
|
RBAC -->|일반 사용자| UserAPI[사용자 API]
|
|
RBAC -->|읽기 전용| ReadOnlyAPI[조회 API]
|
|
|
|
AdminAPI --> Services[백엔드 서비스]
|
|
UserAPI --> Services
|
|
ReadOnlyAPI --> Services
|
|
|
|
Services --> AuditLog[감사 로그]
|
|
|
|
style Auth fill:#4CAF50,color:#fff
|
|
style RBAC fill:#FF9800,color:#fff
|
|
style AuditLog fill:#F44336,color:#fff
|
|
```
|
|
|
|
### 6.2 API 키 관리
|
|
|
|
```mermaid
|
|
graph TB
|
|
User[사용자] -->|API 키 입력| Encrypt[암호화]
|
|
Encrypt -->|AES-256| Store[(암호화 저장소)]
|
|
|
|
Scheduler[스케줄러] -->|필요 시| Decrypt[복호화]
|
|
Store -->|암호화된 데이터| Decrypt
|
|
Decrypt -->|평문 키| BrokerAPI[증권사 API]
|
|
|
|
BrokerAPI -->|응답| Scheduler
|
|
|
|
Note1[메모리에만 평문 존재]
|
|
Note2[로그에 절대 기록 안함]
|
|
|
|
style Encrypt fill:#4CAF50,color:#fff
|
|
style Store fill:#F44336,color:#fff
|
|
style Decrypt fill:#FF9800,color:#fff
|
|
```
|
|
|
|
## 7. 확장성 고려사항
|
|
|
|
### 7.1 수평 확장
|
|
|
|
- **API Gateway**: 로드 밸런서를 통한 다중 인스턴스
|
|
- **Worker 프로세스**: 메시지 큐 기반 작업 분산
|
|
- **데이터베이스**: Read Replica를 통한 읽기 부하 분산
|
|
- **캐시**: Redis Cluster를 통한 분산 캐싱
|
|
|
|
### 7.2 증권사 플러그인 아키텍처
|
|
|
|
```mermaid
|
|
graph TB
|
|
subgraph "Core"
|
|
BrokerInterface[BrokerAdapter<br/>인터페이스]
|
|
end
|
|
|
|
subgraph "플러그인"
|
|
KoreaInvestment[한국투자증권<br/>Adapter]
|
|
Samsung[삼성증권<br/>Adapter]
|
|
Kiwoom[키움증권<br/>Adapter]
|
|
Future[미래 증권사<br/>Adapter]
|
|
end
|
|
|
|
BrokerInterface -.->|구현| KoreaInvestment
|
|
BrokerInterface -.->|구현| Samsung
|
|
BrokerInterface -.->|구현| Kiwoom
|
|
BrokerInterface -.->|구현| Future
|
|
|
|
Balance[balance 컴포넌트] --> BrokerInterface
|
|
|
|
style BrokerInterface fill:#2196F3,color:#fff
|
|
style Future fill:#ddd
|
|
```
|
|
|
|
## 8. 장애 복구
|
|
|
|
### 8.1 장애 시나리오 및 대응
|
|
|
|
| 시나리오 | 영향 | 복구 방안 |
|
|
|---------|------|----------|
|
|
| 증권사 API 장애 | 주문 실행 불가 | 자동 재시도 (지수 백오프), 수동 개입 알림 |
|
|
| 데이터베이스 장애 | 시스템 전체 중단 | Replica로 자동 Failover |
|
|
| 시장 데이터 지연 | 신호 생성 지연 | 캐시 데이터 활용, 타임아웃 처리 |
|
|
| Worker 프로세스 다운 | 특정 작업 중단 | 헬스 체크 실패 시 자동 재시작 |
|
|
| 메시지 큐 장애 | 비동기 작업 중단 | 메시지 영속화, 큐 복구 후 재처리 |
|
|
|
|
### 8.2 백업 전략
|
|
|
|
- **데이터베이스**: 일일 전체 백업 + 트랜잭션 로그 백업 (Point-in-Time Recovery)
|
|
- **설정**: Git 기반 버전 관리
|
|
- **감사 로그**: S3에 불변 저장 (법적 보존 기간 준수)
|
|
- **백테스트 결과**: 주요 결과만 장기 보관
|
|
|
|
## 9. 관련 문서
|
|
|
|
- [시스템 개요](./01-overview.md)
|
|
- [공통 데이터 모델](./03-data-models.md)
|
|
- [주요 워크플로우](./04-workflows.md)
|
|
- [구현 로드맵](./05-roadmap.md)
|
|
|
|
### 구성요소 상세 문서
|
|
- [Phase 1 컴포넌트](../components/phase1/)
|
|
- [Phase 2 컴포넌트](../components/phase2/)
|
|
- [Phase 3 컴포넌트](../components/phase3/)
|