# Auto Stock Trading System — Claude Context Guide

> **Core Directive**: This document defines the strategies, rules, and architecture for the system. All code modifications and analysis must strictly adhere to these guidelines.

---

## 1. Project Overview

### 1.1 Tech Stack
- **Backend**: Python 3.11, FastAPI, SQLAlchemy (Async), PostgreSQL, Redis
- **Frontend**: React, TypeScript, Vite, Recharts
- **Infrastructure**: Docker Compose, Nginx
- **AI Layer**: Claude 3.5 Sonnet / Gemini 2.0 Flash (Switch via `.env`)
- **Integration**: KIS REST/WebSocket API, MCP Server (stdio)

### 1.2 Environment (`.env`)
- **AI_PROVIDER**: `gemini` or `claude`
- **KIS_MODE**: `virtual` or `real`
- **TOKEN_SAVE_MODE**: `true` (Compresses JSON, limits chart data to 30 days)

---

## 2. Directory Structure

### 2.1 Backend (`backend/app/`)
- **API**: `api/endpoints/` (Market data, Portfolio, Trades)
- **Core**: `market_data.py`, `portfolio.py`, `trades.py`

### 2.2 Services (`backend/app/services/`)
- **Strategies**: `mean_reversion_strategy.py` (v2), `short_term_strategy.py`, `kosdaq_scanner.py`
- **Analysis**: `feature_engineering.py`, `ml_ensemble.py`, `tensorflow_predictor.py`
- **Risk & Utils**: `risk_management.py`, `loss_tracker.py`, `mdd_manager.py`
- **Architecture**: `db_worker.py` (Async DB Writer)

### 2.3 MCP (`mcp-server/`)
- `stdio_server.py`, `auto_trade_claude.py`, `trade_monitor.py`

---

## 3. Architecture Principles (Critical)

### 3.1 Separation of Concerns
- **Real-time Layer**: Handles API callbacks, Websocket broadcasts, and memory caching. **Zero DB I/O allowed.**
- **Persistence Layer**: Handles DB INSERT/UPDATE operations via background workers.

### 3.2 Async DB Worker Rule
- **Direct DB Access Ban**: Never call `AsyncSessionLocal()` or `commit()` inside API callbacks or real-time schedulers.
- **Queue Usage**: All data persistence (Trade history, Analysis results) must be sent to `db_task_queue` in `db_worker.py`.
- **Worker**: The background worker processes the queue and handles safe DB transactions sequentially.

---

## 4. Coding Guidelines

### 4.1 Stability
- **No Breaking Changes**: Never alter existing function/class signatures.
- **Versioning**: Use `_v2`, `_v3` suffixes for new strategy implementations.

### 4.2 Optimization
- **JSON Handling**: Always use `core.json_helpers._dumps()` instead of `json.dumps`.
- **Prompt Engineering**: Minimize tokens, use compact formats.

---

## 5. Risk Management Rules

### 5.1 Position Sizing
- **Max Allocation**: 3-4% of total capital per stock.
- **Max Count**: 20-25 stocks max.
- **Leverage**: Max 20% of total capital for Inverse/Leveraged ETFs.

### 5.2 Stop Loss (SL) & Take Profit (TP)
- **SL Base**: -6% (Stable), -10% (Volatile).
- **SL ATR**: `Entry Price - (2.5 * ATR)`. (Priority over base SL)
- **TP**: Sell 50% at +2R profit.
- **Trailing Stop**: `High - (1.5 * ATR)` for remaining 50%.

### 5.3 MDD Control
- **MDD -10%**: Stop new entries. Reduce position sizes by 30%. **Stop Short-term Strategy.**
- **MDD -20%**: Force reduce all positions by 50%. Liquidate leveraged assets first.

### 5.4 Filters
- **Price**: > 5,000 KRW (Korea), > $4 (US). (Exceptions: ETFs, REITs)
- **Correlation**: Max 3 stocks per sector. Reject entry if correlation > 0.7 with portfolio.

---

## 6. Strategy A: RSI + Bollinger Mean Reversion v2

### 6.1 Market Regime (Daily)
- **BULL**: KOSPI200 > MA200 AND MA200 Slope > 0.
- **BEAR**: KOSPI200 < MA200 AND MA200 Slope < 0.
- **SIDEWAYS**: ADX < 20 OR Slope ≈ 0. **(Ignore all signals)**

### 6.2 Entry Conditions
- **Bull Market**: RSI(14) < 25, Price within BB Lower (-3% to +1.5%), Vol > 20MA.
- **Bear Market**: RSI(14) < 30, Price < BB Lower, Vol > 1.5x 20MA, Reversal candle required.
- **Pre-emptive**: Daily RSI < 40 AND 60m RSI < 30 AND Breakout MA5.

### 6.3 Exit Conditions
- **Partial**: RSI > 50 OR Price > BB Mid OR Profit > 2*ATR.
- **Full**: RSI > 65 OR Price > BB Upper (99%) OR Trailing Stop.

---

## 7. Strategy B: Aggressive Growth

### 7.1 Kosdaq Scanner (Swing)
- **Scope**: All Kosdaq (~1600).
- **Filter**: Price > 5,000 KRW, Top 20% Volume.
- **Score**: `0.5*RSI + 0.3*BB + 0.2*Vol`. Pick Top 20.
- **Allocation**: 25% of Capital.

### 7.2 Short-term Strategy (15m)
- **Target**: Stocks with Daily RSI < 40.
- **Entry**: 15m RSI < 30, Price near BB Lower, MA5 Breakout, Vol > 1.3x.
- **Exit**: 15m RSI > 55 OR Profit > 1.5 * ATR(15m).
- **Allocation**: Max 25% of Capital. **Disable if MDD < -10%.**

---

## 8. Instructions for Claude

### 8.1 Critical Checkpoints
1.  **Architecture**: Ensure all DB writes use `db_worker.py`.
2.  **Safety**: Always apply Risk Rules (Section 5) to every trade.
3.  **Regime**: Do NOT suggest entries in SIDEWAYS regime.
4.  **Testing**: No real trading without Backtest + Walk-forward validation.

### 8.2 Response Format
- Use `_dumps()` for JSON.
- Create new files for new features.
- Do not modify existing signatures.

*Last updated: 2026-02-24*