biggfish/PROJECT_OVERVIEW.md

# 🐟 BIGGFISH Project Overview

## Mission
Turn $100 into $1,000 in 2 months through intelligent, autonomous stock trading.

## Core Philosophy
- **Start Small, Scale Smart**: Begin with small cap momentum plays, gradually transition to blue chips
- **Research-Driven**: Continuous market analysis and learning
- **Risk-Managed**: Strict position limits and stop losses
- **Transparent**: Daily reports and strategy proposals
- **Paper Trading**: Zero real-world risk during development

## System Architecture

### 1. Trading Engine (`src/trading/broker.py`)
**Purpose**: Interface with Alpaca Markets for paper trading

**Capabilities**:
- Connect to Alpaca paper trading API
- Execute market and limit orders
- Track portfolio value and positions
- Monitor account status and buying power
- Get historical price data

**Safety Features**:
- Always uses paper trading (hardcoded)
- Position size limits enforced
- Market hours checking

### 2. Research Module (`src/research/screener.py`)
**Purpose**: Scan markets and identify trading opportunities

**Stock Universe**:
- **Small Caps** (~30 tickers): High growth potential, higher volatility
- **Mid Caps** (~10 tickers): Balanced growth and stability
- **Large Caps** (~10 tickers): Blue chips for stability

**Screening Criteria**:
- Volume surge detection (>1.5x average = bullish)
- Price momentum (weekly/monthly trends)
- Volatility analysis (sweet spot: 2-5%)
- Minimum price filter ($2+, avoid penny stocks)
- Minimum volume filter (500K+ daily)

**Scoring System** (0-100):
- Base: 50 points
- Momentum bonus: +10 to +15 points
- Volume surge: +10 to +20 points
- Volatility: +10 if optimal, -10 if excessive
- Penalties for low price/volume

### 3. Strategy Engine (`src/strategies/manager.py`)
**Purpose**: Generate trading strategies from opportunities

**Strategy Types**:

1. **Momentum Breakout**
   - Trigger: Volume surge >1.5x + price momentum >3%
   - Target: 15% gain
   - Stop Loss: 7%
   - Best for: Strong trending stocks

2. **Mean Reversion**
   - Trigger: Recent pullback + low volatility
   - Target: 10% gain
   - Stop Loss: 5%
   - Best for: Oversold quality stocks

3. **Swing Trade**
   - Trigger: General opportunity
   - Target: 12% gain
   - Stop Loss: 6%
   - Best for: Mixed signals

**Risk Management**:
- Max position size: 20% of portfolio
- Max cash per trade: 30%
- Risk/Reward calculated for each trade
- Stop losses automatically set

### 4. Reporting System (`src/reporting/reporter.py`)
**Purpose**: Track performance and communicate insights

**Daily Reports Include**:
- Portfolio value and cash position
- Day P/L (profit/loss)
- Goal progress ($100 → $1,000)
- Open positions with P/L
- Performance metrics

**Strategy Proposals Include**:
- Entry, target, and stop prices
- Position size and risk
- Detailed rationale
- Technical signals

## Trading Progression

### Phase 1: Small Cap Focus ($100 → $200)
- **Timeframe**: Weeks 1-2
- **Universe**: 100% small caps
- **Strategy**: Aggressive momentum plays
- **Goal**: Double initial capital through high-volatility winners

### Phase 2: Mid Cap Mixed ($200 → $400)
- **Timeframe**: Weeks 3-4
- **Universe**: 80% small, 20% mid caps
- **Strategy**: Balance momentum with stability
- **Goal**: Consistent gains with reduced risk

### Phase 3: Diversified ($400 → $700)
- **Timeframe**: Weeks 5-6
- **Universe**: 60% small, 30% mid, 10% large caps
- **Strategy**: Portfolio diversification
- **Goal**: Protect gains while growing

### Phase 4: Balanced ($700 → $1,000)
- **Timeframe**: Weeks 7-8
- **Universe**: 40% small, 30% mid, 30% large caps
- **Strategy**: Capital preservation with selective opportunities
- **Goal**: Cross $1,000 finish line safely

## Configuration System

All parameters in `config/config.json`:

```json
{
  "trading": {
    "initial_capital": 100,
    "target_capital": 1000,
    "max_position_size_pct": 20,      // Max 20% per position
    "max_daily_loss_pct": 5,          // Stop trading if -5% in a day
    "max_total_loss_pct": 15,         // Emergency brake at -15%
    "require_approval": true          // Human approval required
  },
  "research": {
    "screening_interval_hours": 6,    // Scan every 6 hours
    "news_check_interval_hours": 2,   // News every 2 hours
    "max_watchlist_size": 50,
    "min_volume": 500000,
    "min_price": 2.0
  }
}
```

## Automation Features

**Scheduled Tasks**:
- ✅ Market scanning every 6 hours
- ✅ News monitoring every 2 hours
- ✅ Daily reports at 4:30 PM ET
- ✅ Automatic strategy generation

**Manual Control**:
- Strategy approval/rejection
- Emergency stop
- Parameter adjustments
- Manual trade execution

## Safety Mechanisms

1. **Paper Trading Lock**: Hardcoded to use paper API
2. **Position Limits**: Max 20% of portfolio per position
3. **Daily Circuit Breaker**: Stop if -5% in one day
4. **Total Loss Limit**: Emergency stop at -15% total loss
5. **Approval Gate**: All strategies require human approval
6. **Stop Losses**: Automatic stops on every position
7. **Market Hours**: Only trade during market hours

## Data Storage

```
data/
├── stocks/           # Stock data cache
├── reports/          # Daily performance reports (JSON)
└── trades/           # Trade history and logs
```

## CLI Tools

```bash
# Real-time portfolio status
python src/cli.py status

# Scan for opportunities
python src/cli.py scan [--focus small_cap|mid_cap_mixed|balanced]

# Generate strategies
python src/cli.py strategies

# Check market hours
python src/cli.py market
```

## Workflow Example

**Morning** (9:00 AM):
1. System wakes up, checks if market is open
2. Runs initial scan of small cap universe
3. Generates 3-5 strategy proposals
4. Sends proposals to you via Telegram/logs

**You Review** (9:30 AM):
- Review proposals: "SOUN momentum breakout looks good ✅"
- Approve or reject each strategy
- System executes approved trades

**Midday** (12:00 PM):
- System checks news for holdings
- Monitors positions against stop losses
- No new scans (next scan at 3 PM)

**Afternoon** (3:00 PM):
- Second scan of the day
- May generate new proposals for next day

**Market Close** (4:30 PM):
- Daily report generated
- Shows: portfolio value, P/L, goal progress
- Highlights: best/worst performers
- Tomorrow: strategy preview

## Success Metrics

**Week 1-2**: $100 → $200 (100% gain)
- Minimum 3 profitable trades
- Max 2 losses
- Average gain per winner: 15%+

**Week 3-4**: $200 → $400 (100% gain)
- Consistent 10%+ weekly gains
- Diversification into mid caps
- Reduced volatility

**Week 5-6**: $400 → $700 (75% gain)
- Blue chips added for stability
- Portfolio beta reduction
- Risk-adjusted returns optimized

**Week 7-8**: $700 → $1,000 (43% gain)
- Capital preservation mode
- Selective high-confidence plays
- Goal achievement

## Future Enhancements

**Phase 2 Features** (after reaching $1,000):
- [ ] ML-based pattern recognition
- [ ] Sentiment analysis from news/social
- [ ] Options trading strategies
- [ ] Backtesting engine
- [ ] Multi-timeframe analysis
- [ ] Sector rotation strategies
- [ ] Earnings play automation

**Integration Ideas**:
- Telegram bot for mobile approval
- Discord/Slack notifications
- Web dashboard for monitoring
- Real-time alerts for big moves

## Risk Disclaimer

This is an **experimental system** operating in **paper trading mode**. 

- ⚠️ Not financial advice
- ⚠️ Past performance ≠ future results
- ⚠️ High risk strategies used
- ⚠️ Do not use with real money without extensive testing

## Getting Started

See `SETUP.md` for detailed setup instructions.

---

**Let's go catch that BIGGFISH! 🐟🚀**