# 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
```