# 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/)