system-specs/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Repository Overview

This is the specification repository for QuantBench, a quantitative trading platform for individual investors. It contains system architecture documentation, component specifications, and design diagrams but no actual implementation code.

The platform enables:

• Multi-account management with multiple brokers (한국투자증권, 삼성증권, 키움증권)
• Container-based asset isolation for running multiple strategies in parallel
• Strategy-based automated trading with backtesting
• Risk management and performance analytics

System Architecture

Three-Phase Development Approach

Phase 1: MVP (Core Trading System)

• balance: Broker API integration and account management
• mgmt: Virtual container management for asset isolation
• strategy: Strategy implementation, execution, and backtesting
• scheduler: Automated execution scheduling with approval workflows
• risk: Pre-trade risk validation and position monitoring
• data: Market data collection, storage, and quality management

Phase 2: Production Ready

• analytics: Performance measurement, attribution analysis, and reporting
• monitor: System health monitoring, anomaly detection, and alerting

Phase 3: Enterprise Grade

• audit: Immutable audit logging and compliance reporting
• simulation: Paper trading, scenario testing, and parameter optimization

Key Architectural Concepts

Container-Based Asset Isolation: The core innovation is the virtual container system that allows multiple strategies to run independently within a single brokerage account. Each container has:

• Virtual balance tracking (isolated from other containers)
• Independent risk limits and constraints
• Dedicated strategy assignment
• Rebalancing schedules

Strategy Execution Flow:

scheduler trigger → mgmt (container info) → strategy (signal generation) →
data (market data) → risk (validation) → balance (order execution) →
mgmt (update positions) → analytics (performance calc) → monitor (alerts)

Risk Management Integration: All orders pass through risk validation before execution, checking:

• Balance sufficiency
• Position size limits
• Concentration limits
• Value at Risk (VaR)
• Maximum drawdown
• Leverage limits

Component Relationships

Core Dependencies

• scheduler orchestrates execution by calling mgmt, strategy, risk, and balance
• strategy depends on data for market data and risk for validation
• mgmt manages virtual balances and coordinates with balance for actual positions
• analytics consumes data from mgmt, balance, and data for performance calculation
• monitor observes all components and triggers alerts

Data Flow

• Real-time market data: Broker APIs → data → Redis cache → strategy/monitor
• Historical data: External providers → data → Time-series DB → analytics/backtesting
• Order flow: strategy signals → risk validation → balance execution → mgmt reconciliation

Working with This Repository

File Structure

• specification.md: Comprehensive component specifications with data models (44KB, Korean)
• diagram.md: Mermaid diagrams for architecture visualization
• README.md: Empty placeholder

Understanding the Specifications

The specification.md file is structured with:

1. Component responsibilities and main functions
2. TypeScript interface definitions for data models
3. Function signatures with descriptions
4. Workflow examples showing component interactions

Each component section follows this pattern:

### Component Name (책임)
#### 주요 기능
- Function descriptions with signatures
**데이터 모델**
- TypeScript interfaces

Key Design Patterns

Broker Abstraction: The BrokerAdapter interface in the balance component abstracts different broker APIs (한국투자증권, 삼성증권, 키움증권) behind a unified interface for portability.

Strategy Interface: All strategies must implement StrategyInterface with required methods:

• initialize(context: StrategyContext)
• generateSignals(data: MarketData): Signal[]

Approval Workflow: The scheduler supports both AUTO and APPROVAL_REQUIRED modes. In approval mode, execution waits for user confirmation before submitting orders.

Immutable Audit Trail: Phase 3 introduces hash-chained audit events with previousHash links to ensure tamper-proof logging.

Important Considerations

Multi-Language Documentation

All specifications are written in Korean. Component names and code interfaces use English, but descriptions, comments, and documentation are in Korean.

No Implementation Code

This repository contains only specifications and diagrams. When discussing implementation:

• Reference the TypeScript interfaces defined in specifications
• Maintain consistency with the defined data models
• Follow the component interaction patterns described in workflows

Risk-First Design

The architecture prioritizes safety:

• All orders must pass risk validation before execution
• Container-level constraints prevent over-allocation
• Reconciliation functions detect discrepancies between virtual and actual balances
• Stop-loss and take-profit mechanisms support automatic position closure

Real-World Trading Constraints

The design accounts for practical trading considerations:

• Market hours and holidays (Korean exchanges)
• Commission and slippage modeling
• Order types (market, limit, stop)
• Partial fills and order status tracking
• Corporate actions (dividends, stock splits)

Diagram Reference

The diagram.md file contains 10 Mermaid diagrams:

1. Overall system architecture (all phases)
2. Phase 1 component relationships
3. Phase-by-phase component structure
4. Strategy execution sequence diagram
5. Risk management flow
6. Data flow diagram
7. Container lifecycle state machine
8. Approval workflow
9. Monitoring and alerting system
10. Simulation environment structure

Use these diagrams to understand component interactions visually before making specification changes.

Specification Modification Guidelines

When updating specifications:

1. Maintain Interface Consistency: Changes to data models should be reflected across all dependent components
2. Update All Phases: If a core data model changes, check impact across all three phases
3. Preserve Type Safety: Keep TypeScript interfaces complete with all required fields
4. Document Workflows: Update sequence descriptions when component interactions change
5. Version Strategies: Strategy changes should use the versioning system (StrategyVersion)

Related Systems

The specifications reference external systems that must be integrated:

• Broker APIs: 한국투자증권, 삼성증권, 키움증권
• Data providers: Yahoo Finance, Alpha Vantage
• Infrastructure: PostgreSQL, Redis, Message Queue (Kafka/RabbitMQ), S3
• Notification channels: Email, SMS, Push, Slack