167 lines
6.9 KiB
Markdown
167 lines
6.9 KiB
Markdown
# 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
|