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:

{
  "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

# 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! 🐟🚀