# Market Watch - Multiplayer GARP Paper Trading Simulator

Multiplayer paper trading simulator implementing a **Growth at a Reasonable Price (GARP)** strategy. Compete against Case (AI) and other players.

## How It Works

- **Create or join a game** with configurable starting cash
- **Trade manually** via the web portal or Telegram
- **Case (AI)** trades autonomously using the GARP strategy
- **Leaderboard** tracks who's winning by % return

## GARP Filter Criteria

| Metric | Threshold |
|--------|-----------|
| Revenue Growth | ≥ 10% |
| Trailing P/E | < 25 |
| Forward P/E | < 15 |
| PEG Ratio | < 1.2 (if available) |
| EPS Growth | > 15% |
| ROE | > 5% |
| Quick Ratio | > 1.5 (if available) |
| Debt/Equity | < 35% (if available) |
| Market Cap | > $5B |

### Case's Trading Rules
- **Buy:** GARP filter pass + RSI < 70 + not within 2% of 52wk high + max 10% per position + max 15 positions
- **Sell:** Fails GARP rescan OR 10% trailing stop-loss OR RSI > 80
- **Universe:** S&P 500 + S&P 400 MidCap (~900 stocks)

## Architecture

| File | Description |
|------|-------------|
| `game_engine.py` | Multiplayer game/player/portfolio engine |
| `scanner.py` | GARP scanner across S&P 500 + 400 |
| `trader.py` | Case's autonomous trading logic |
| `run_daily.py` | Daily orchestrator (scan → trade → snapshot → alert) |
| `portfolio.py` | Backward-compatible wrapper for single-player |
| `portal/server.py` | Web dashboard with multiplayer UI |

### Data Structure
```
data/games/{game_id}/
├── game.json                    # Game config, players, rules
└── players/{username}/
    ├── portfolio.json           # Current positions & cash
    ├── trades.json              # Trade history
    └── snapshots.json           # Daily value snapshots
```

## Web Portal

**URL:** http://marketwatch.local (or http://localhost:8889)

- **Home:** List of games, create new game
- **Game page:** Leaderboard, join game
- **Player page:** Portfolio, trade form, performance chart, trade history

### API Endpoints

| Method | Endpoint | Description |
|--------|----------|-------------|
| POST | `/api/games` | Create game (form: name, starting_cash, end_date) |
| POST | `/api/games/{id}/join` | Join game (form: username) |
| POST | `/api/games/{id}/players/{user}/trade` | Trade (form: action, ticker, shares) |
| GET | `/api/games/{id}/leaderboard` | Get leaderboard JSON |
| GET | `/api/games/{id}/players/{user}/portfolio` | Get portfolio JSON |

## Systemd Services

| Service | Schedule |
|---------|----------|
| `market-watch.timer` | Mon-Fri 9:00 AM + 3:30 PM CST |
| `market-watch-portal.service` | Always running (port 8889) |

```bash
systemctl --user status market-watch.timer
systemctl --user status market-watch-portal
journalctl --user -u market-watch -f
```

## Telegram

Players can trade via: `buy AAPL 10` or `sell BAC 50`
Daily summaries with leaderboard sent automatically.