# Crypto News Signal Dashboard — Design Spec

## Overview

Binance 현물(Spot) 코인을 대상으로 뉴스, 소셜미디어, 기술적 분석, AI 분석을 종합하여 매수/매도 시그널을 생성하고, 가상 $200 포트폴리오로 시뮬레이션하는 대시보드.

## Tech Stack

- **App**: Streamlit (단일 프로세스, Sidebar + Detail 레이아웃)
- **Scheduler**: APScheduler (in-process background thread)
- **Storage**: SQLite WAL mode (시그널 이력, 포트폴리오, 거래 기록) + JSON cache (API 응답)
- **Language**: Python 3.11+

## Application Topology

Streamlit이 메인 프로세스로 동작하며, FastAPI 없이 Python 모듈을 직접 import하여 사용한다.

```
[Streamlit Process (main)]
  ├── imports agents/* (직접 호출)
  ├── imports engine/* (직접 호출)
  ├── imports data/* (직접 호출)
  ├── APScheduler (in-process, background thread)
  │   └── 15분마다 agents 실행 → engine 업데이트
  └── Binance WebSocket (background thread)
      └── 실시간 가격 업데이트 → st.session_state
```

- **단일 프로세스**: Streamlit이 모든 모듈을 직접 import. 별도 FastAPI 서버 불필요
- **Scheduler**: APScheduler가 Streamlit 프로세스 내 background thread로 동작
- **WebSocket**: python-binance의 ThreadedWebsocketManager로 background에서 가격 수신
- **Storage**: SQLite WAL 모드 (concurrent read 허용, single-writer)

## Architecture

### Data Sources

| Source | API | Purpose | Update Cycle |
|--------|-----|---------|-------------|
| Binance | REST + WebSocket | 가격, 거래량, OHLCV, 시가총액 순위 | 실시간 (WebSocket) |
| CryptoPanic / NewsAPI | REST | 크립토 뉴스 헤드라인 | 15분 |
| Twitter/X API | REST | 코인별 언급량, 감성 | 15분 |
| Reddit API | REST | r/cryptocurrency 등 감성 분석 | 15분 |
| Claude API | REST | 시장 상황 종합 분석, 뉴스 영향도 판단 | 15분 |

### Analysis Agents

4개의 독립적인 분석 에이전트가 각 코인에 대해 0~100 점수를 산출한다.

#### 1. Technical Agent (기본 가중치: 60%)
- **Indicators**: RSI(14), MACD(12,26,9), Bollinger Bands(20,2), 이동평균(SMA 20/50/200)
- **Volume Analysis**: 거래량 급증 감지, OBV(On-Balance Volume)
- **Candlestick Patterns**: Engulfing, Doji, Hammer 등 주요 패턴
- **Input**: Binance OHLCV 데이터 (1h, 4h, 1d 캔들)
- **Output**: 0~100 기술적 점수

#### 2. News Agent (기본 가중치: 20%)
- **Sources**: CryptoPanic API, NewsAPI
- **Analysis**: 헤드라인 감성 분석 (positive/negative/neutral)
- **Scoring**: 최근 24시간 뉴스의 감성 비율 + 뉴스 영향도(중요도) 가중
- **Output**: 0~100 뉴스 감성 점수

#### 3. Social Agent (기본 가중치: 10%)
- **Sources**: Twitter/X API, Reddit API (r/cryptocurrency, r/binance)
- **Metrics**: 코인별 언급량 추세, 감성 분석, 인플루언서 언급 가중치
- **Analysis**: 24시간 언급량 변화율 + 감성 비율
- **Output**: 0~100 소셜 감성 점수

#### 4. AI Agent (기본 가중치: 10%)
- **Provider**: Claude API (Anthropic)
- **Input**: 최근 뉴스 요약, 기술적 지표 요약, 소셜 감성 요약, 시장 전반 상황
- **Task**: 종합적 시장 컨텍스트 판단, 각 코인의 단기 전망 평가
- **Output**: 0~100 AI 종합 점수 + 텍스트 분석 요약

### Signal Engine

#### Score Aggregator
```
composite_score = (technical * w1) + (news * w2) + (social * w3) + (ai * w4)
where w1 + w2 + w3 + w4 = 1.0
defaults: w1=0.6, w2=0.2, w3=0.1, w4=0.1
```

#### Signal Classification
- **BUY**: composite_score >= 70
- **HOLD**: 40 <= composite_score < 70
- **SELL**: composite_score < 40

#### Surge Detector
- 바이낸스 전체 코인 중 거래량이 24h 평균 대비 300% 이상 급증한 코인을 자동 감지
- 감지된 코인을 모니터링 목록에 자동 추가
- Top 50에 없더라도 급등/급락 코인 포착 가능

### Coin Scope
- **Base**: 시가총액 Top 50 (USDT 페어 기준)
- **Auto-add**: 거래량 급증 코인 (Surge Detector)
- **User pin**: 사용자가 수동으로 추가한 코인
- **Pair**: 모든 코인은 USDT 현물 페어 기준

## Portfolio Simulator

### Rules
- **초기 자본**: $200 (가상)
- **거래 방식**: Binance 현물(Spot)만 사용. 레버리지/마진/선물/공매도 없음
- **최대 동시 포지션**: 5개

### Entry (매수)
- Signal score >= 70인 코인 중 점수가 높은 순서대로 매수
- Position size: 가용 현금의 15~30% (점수가 높을수록 큰 비중)
  - Score 70~79: 15% of cash
  - Score 80~89: 20% of cash
  - Score 90~100: 30% of cash
- 가용 현금이 없으면 매수하지 않음
- **최소 포지션**: $15 미만이면 매수하지 않음 (바이낸스 최소 주문 규모 고려)

### Exit (매도)
- **Signal exit**: 보유 코인의 score가 39 이하로 하락 시 전량 매도
- **Stop-loss**: 진입가 대비 -8% 하락 시 자동 손절
- **Take-profit 1차**: 진입가 대비 +15% 상승 시 50% 부분 익절
- **Take-profit 2차**: 진입가 대비 +25% 상승 시 나머지 전량 익절

### Reinvestment (재투자)
- 매도 후 현금은 가용 풀로 복귀
- 다음 15분 분석 주기에 새로운 BUY 시그널 탐색
- 가장 높은 점수의 코인부터 우선 배분

### P&L Tracking
- **Per-trade P&L**: 각 거래의 실현 손익 (진입가 vs 퇴장가)
- **Per-position P&L**: 보유 중인 포지션의 미실현 손익 (진입가 vs 현재가)
- **Total portfolio P&L**: 초기 자본 대비 총 수익률
- **Win rate**: 수익 거래 / 전체 거래
- **Average gain/loss**: 평균 수익 / 평균 손실

## Dashboard (Streamlit)

### Layout: Sidebar + Detail

#### Sidebar (Left)
- 코인 목록 + 종합 점수
- 색상 코딩: BUY(green), HOLD(yellow), SELL(red)
- 코인 클릭 시 우측 Detail 영역 변경
- 정렬: 점수 높은 순 (BUY 순위)
- 하단: 가중치 슬라이더 (사용자 커스텀)

#### Detail Area (Right)
선택한 코인의 상세 정보를 4개 패널로 표시:

1. **Chart Panel**: 캔들스틱 차트 + RSI/MACD/BB 오버레이. plotly 사용
2. **News Panel**: 최근 뉴스 헤드라인 목록 + 감성 태그
3. **Social Panel**: Twitter/Reddit 언급량 추세 차트 + 주요 글
4. **AI Panel**: Claude 분석 요약 텍스트 + 시그널 근거

#### Portfolio Tab
- Summary bar: 초기자본, 현재가치, 총 P&L, 승률, 가용 현금
- Current Holdings: 보유 포지션 테이블 (코인, 배분금액, 수량, 평균진입가, 현재가, P&L)
- Trade History: 청산 거래 이력 (날짜, 코인, 진입/퇴장가, 사이즈, P&L, 사유)
- Allocation Chart: 원형 차트 (코인별 비중 + 현금)

## Update Cycle

| Component | Cycle | Method |
|-----------|-------|--------|
| Price data | Realtime | Binance WebSocket |
| Technical indicators | On price update | Calculated from OHLCV |
| News analysis | Every 15 min | APScheduler → CryptoPanic/NewsAPI |
| Social analysis | Every 15 min | APScheduler → Twitter/Reddit API |
| AI analysis | Every 15 min | APScheduler → Claude API |
| Signal scoring | Every 15 min | After all agents complete |
| Portfolio rebalance | Every 15 min | After signal scoring |

## Project Structure

```
crypto_news_trading/
├── run.py                   # Streamlit entry point (streamlit run run.py)
├── config.py                # API keys, settings, defaults
├── requirements.txt
├── .env                     # API keys (gitignored)
│
├── agents/
│   ├── __init__.py
│   ├── technical.py         # Technical analysis agent
│   ├── news.py              # News sentiment agent
│   ├── social.py            # Social media agent
│   └── ai_analyst.py        # Claude AI agent
│
├── engine/
│   ├── __init__.py
│   ├── signal.py            # Score aggregator + signal classifier
│   ├── surge.py             # Volume surge detector
│   └── portfolio.py         # Portfolio simulator + P&L tracker
│
├── data/
│   ├── __init__.py
│   ├── binance_ws.py        # Binance WebSocket client
│   ├── binance_rest.py      # Binance REST client
│   ├── news_client.py       # CryptoPanic / NewsAPI client
│   ├── social_client.py     # Twitter / Reddit client
│   └── db.py                # SQLite DB manager
│
├── dashboard/
│   ├── app.py               # Streamlit main app
│   ├── sidebar.py           # Coin list sidebar
│   ├── detail.py            # Detail panels (chart, news, social, ai)
│   └── portfolio_view.py    # Portfolio dashboard
│
├── scheduler/
│   └── jobs.py              # APScheduler job definitions
│
├── logs/                    # Log files (gitignored)
│
└── db/
    └── schema.sql            # SQLite schema
```

## Database Schema (SQLite)

### signals
| Column | Type | Description |
|--------|------|-------------|
| id | INTEGER PK | Auto increment |
| coin | TEXT | Symbol (e.g., BTCUSDT) |
| timestamp | DATETIME | Signal time |
| technical_score | REAL | 0~100 |
| news_score | REAL | 0~100 |
| social_score | REAL | 0~100 |
| ai_score | REAL | 0~100 |
| composite_score | REAL | Weighted sum |
| signal | TEXT | BUY / HOLD / SELL |

### trades
| Column | Type | Description |
|--------|------|-------------|
| id | INTEGER PK | Auto increment |
| coin | TEXT | Symbol |
| side | TEXT | BUY / SELL |
| price | REAL | Execution price |
| quantity | REAL | Coin quantity |
| amount_usd | REAL | USD value |
| timestamp | DATETIME | Trade time |
| reason | TEXT | Signal/stop-loss/take-profit |

### positions
| Column | Type | Description |
|--------|------|-------------|
| id | INTEGER PK | Auto increment |
| coin | TEXT | Symbol |
| entry_price | REAL | Average entry price |
| quantity | REAL | Current quantity |
| invested_usd | REAL | Total USD invested |
| status | TEXT | OPEN / CLOSED |
| opened_at | DATETIME | Position open time |
| closed_at | DATETIME | Position close time (nullable) |

### portfolio
| Column | Type | Description |
|--------|------|-------------|
| id | INTEGER PK | Auto increment |
| timestamp | DATETIME | Snapshot time |
| total_value | REAL | Portfolio total value |
| cash | REAL | Available cash |
| pnl | REAL | Total P&L |
| pnl_pct | REAL | P&L percentage |

## Failure Handling

| Failure | Recovery |
|---------|----------|
| Binance WebSocket 끊김 | 자동 reconnect (python-binance 내장), 3회 실패 시 REST fallback |
| CryptoPanic/NewsAPI 실패 | 캐시된 마지막 결과 사용, 뉴스 점수를 50 (neutral)로 설정 |
| Twitter API 미사용/실패 | Reddit만으로 소셜 점수 산출 |
| Reddit API 실패 | 소셜 점수를 50 (neutral)로 설정 |
| Claude API 타임아웃 | AI 점수를 50으로 설정, 이전 분석 텍스트 유지 |
| Agent가 점수 미산출 | 해당 에이전트 점수 50, 나머지 에이전트로 가중 재배분 |

## Rate Limit & Cost

### API Call Budget (per 15-min cycle)
- **Binance REST**: ~5 calls (Top 50 목록 + surge scan). WebSocket은 별도
- **CryptoPanic**: ~1 call (전체 뉴스 조회 후 코인별 필터링)
- **Reddit**: ~3 calls (subreddit별 조회)
- **Twitter**: ~5 calls (있을 경우)
- **Claude API**: ~2-3 calls (코인을 배치로 묶어 분석. Top 10은 매 주기, 나머지는 1시간 간격)

### Claude API 예상 비용
- 배치 분석: ~2,000 input tokens + ~500 output tokens per call
- 하루 ~150 calls → 월 ~$5-15 (Sonnet 기준)

## Logging

- Python `logging` 모듈, `RotatingFileHandler` (10MB, 5 backups)
- 로그 레벨: 시그널 결정(INFO), 거래 실행(INFO), API 에러(WARNING), 시스템 에러(ERROR)
- 로그 파일: `logs/app.log`

## Data Retention

- signals 테이블: 90일 보관, 이후 일별 요약으로 집계 후 삭제
- trades/positions: 영구 보관
- portfolio 스냅샷: 90일 보관

## Database Schema Additions

### settings
| Column | Type | Description |
|--------|------|-------------|
| key | TEXT PK | Setting name |
| value | TEXT | JSON-encoded value |

사용자 가중치, surge 임계값, 포트폴리오 설정 등을 저장.

## API Keys Required

| Service | Env Variable | Required |
|---------|-------------|----------|
| Binance | BINANCE_API_KEY, BINANCE_SECRET | Yes |
| CryptoPanic | CRYPTOPANIC_API_KEY | Yes |
| NewsAPI | NEWS_API_KEY | Optional (fallback) |
| Twitter/X | TWITTER_BEARER_TOKEN | Optional (유료 API, 없으면 Reddit만 사용) |
| Reddit | REDDIT_CLIENT_ID, REDDIT_SECRET | Yes |
| Anthropic (Claude) | ANTHROPIC_API_KEY | Yes |