# Quantarena v2 — Vollständige Projektdokumentation

## Überblick
Quantarena v2 ist die Erweiterung der KI-Trading-Arena. Statt 3 Bots treten **9 KI-Bots** in **3 Teams** gegeneinander an, plus ein 10. **Consensus-Bot**, der per Mehrheitsentscheid handelt. Jedes Team hat drei Archetypes (Momentum, Macro, Statistisch), jeweils betrieben von einem anderen AI-Provider.

**Live:** https://v2.quantarena.de
**API:** https://api-v2.quantarena.de (Port 8020)
**Server:** 157.180.43.9 (Hetzner VPS, Ubuntu 24.04, User: coob)

**Status:** Frontend in Entwicklung (Mock-Daten). Backend-Services bewusst gestoppt.

---

## Teams & Bots

### Die 3 Teams

| Team | Codename | AI Provider | Farbe | Beschreibung |
|---|---|---|---|---|
| **CORE** | CORE | OpenAI (GPT-4o-mini) | Rot #e63946 | Precise, optimized, relentless. Data-driven dominance. |
| **MONO** | MONOLITH | Anthropic (Claude Haiku 4.5) | Blau #4895ef | Analytical, patient, constitutionally cautious but capable of ruthless precision. |
| **PRISM** | PRISM | Google (Gemini 2.5 Flash) | Grün #a8d8a8 | Multimodal, adaptive, seeing patterns others miss. |

### Die 3 Archetypes

| Archetype | Stil | Bevorzugte Assets | Beschreibung |
|---|---|---|---|
| **APEX** | Momentum | NVDA, TSLA, QQQ, BTC-USD | Aggressiv, jagt Stärke, schneidet Verlierer schnell, lässt Gewinner laufen |
| **MACRO** | Macro | TLT, IEF, GLD, XLF, BTC-USD | Regime-Rotator, geduldig, sieht Zyklen, hält Positionen länger |
| **SENTINEL** | Statistisch | BTC-USD, ETH-USD, SOL-USD, SPY | Mean Reversion, Korrelationen, handelt nur bei statistischem Edge |

### Die 9 Bots (Team x Archetype)

| Bot Name | Team | Archetype | AI Model | Max Position % |
|---|---|---|---|---|
| CORE_APEX | CORE | APEX | GPT-4o-mini | 20% |
| CORE_MACRO | CORE | MACRO | GPT-4o-mini | 15% |
| CORE_SENTINEL | CORE | SENTINEL | GPT-4o-mini | 10% |
| MONO_APEX | MONO | APEX | Claude Haiku 4.5 | 20% |
| MONO_MACRO | MONO | MACRO | Claude Haiku 4.5 | 15% |
| MONO_SENTINEL | MONO | SENTINEL | Claude Haiku 4.5 | 10% |
| PRISM_APEX | PRISM | APEX | Gemini 2.5 Flash | 20% |
| PRISM_MACRO | PRISM | MACRO | Gemini 2.5 Flash | 15% |
| PRISM_SENTINEL | PRISM | SENTINEL | Gemini 2.5 Flash | 10% |

### Der 10. Bot: CONSENSUS (Team VEIL)

- **Kein LLM** — rein algorithmisch
- Liest alle 3 Minuten die letzten Entscheidungen der 9 Bots aus der DB
- **Quorum: 5/9** — wenn mindestens 5 Bots das gleiche Symbol in die gleiche Richtung handeln
- Quantity = Median der Peer-Quantities × Agreement-Ratio
- Team: VEIL (Gold)
- Max Position: 12%

```
Consensus-Logik:
1. Lese letzte 10 Minuten Orders aller 9 Bots
2. Tally votes: pro Symbol + Side (BUY/SELL)
3. Wenn bester Vote >= 5/9: Order ausführen
4. Sonst: FLAT (kein Edge)
5. Size proportional zur Agreement-Stärke (5/9=klein, 9/9=groß)
```

---

## Architektur

### Backend-Services

| Service | Code | Port | Funktion |
|---|---|---|---|
| Overseer v2 | `/opt/trading-v2/overseer/app.py` | 8100 (Docker) | Order-Validierung, Risk Checks |
| DataHub v2 | `/opt/trading-v2/datahub.py` | — | Marktdaten holen, State-Files schreiben |
| Scoreboard v2 | `/opt/trading-v2/scoreboard/api.py` | 8020 | API für Frontend |
| 3x GPT Bots | `/opt/trading-v2/bots/gpt/bot.py` | — | CORE_APEX/MACRO/SENTINEL |
| 3x Claude Bots | `/opt/trading-v2/bots/claude/bot.py` | — | MONO_APEX/MACRO/SENTINEL |
| 3x Gemini Bots | `/opt/trading-v2/bots/gemini/bot.py` | — | PRISM_APEX/MACRO/SENTINEL |
| Consensus Bot | `/opt/trading-v2/bots/consensus/bot.py` | — | THE_CONSENSUS |

### Bot-Architektur (v2 vereinfacht vs v1)

v2 nutzt **keine** 4-Phasen Reasoning Engine. Stattdessen:
1. Bot liest State-File (Preise, Positionen, Standings, Competitors)
2. Ein einzelner LLM-Call mit System Prompt (Team + Archetype) und State als User Message
3. LLM gibt JSON zurück (Symbol, Side, Quantity, Comment)
4. Bot normalisiert und submitted an Overseer

System Prompt wird dynamisch aus `prompts.py` gebaut:
```python
build_prompt(team="CORE", archetype="APEX", bot_name="CORE_APEX")
```

Enthält:
- Team Personality (CORE/MONO/PRISM Flavor Text)
- Archetype Rules (APEX/MACRO/SENTINEL Trading-Stil)
- JSON Output Format
- Erlaubtes Symbol-Universum

### Cycle Interval
- Alle 9 Bots: **180 Sekunden** (3 Minuten)
- Consensus: **180 Sekunden** (3 Minuten)

### State Files
- Pro Bot: `/opt/trading-v2/data/state_{bot_name_lowercase}.json`
- Geschrieben vom DataHub

---

## Overseer v2

### Unterschiede zu v1
- **Striktere Limits** als v1 (v2 hat noch konservative Risk-Settings):
  - Max Quantity: 300
  - Cooldown: 60 Sekunden
  - Max Orders/Tag: 720
  - Max Orders/Minute: 3
- **Position Size Limits pro Bot-Typ:**
  - APEX Bots: max 20% des Kapitals pro Position
  - MACRO Bots: max 15%
  - SENTINEL Bots: max 10%
  - CONSENSUS: max 12%
- **Symbol Universe:** 14 Symbole (SPY, QQQ, AAPL, MSFT, NVDA, TSLA, IWM, TLT, IEF, GLD, XLF, BTC-USD, ETH-USD, SOL-USD)

### Endpoints
- `POST /bot/{bot_name}/order` — Order einreichen
- `GET /health` — Healthcheck

---

## Datenbank

**PostgreSQL in Docker** (gleicher Container wie v1)
- **DB:** `trading_v2`
- **User:** `trading_v2` / `trading_v2pass`
- **Port:** 5432

### Tabellen (gleiche Struktur wie v1)
- `bots` — Bot-Definitionen
- `orders` — Alle Order-Proposals mit Status
- `trades` — Ausgeführte Trades
- `positions` — Aktuelle Positionen (bot_name, symbol, quantity, avg_price)
- `equity_snapshots` — Periodische Equity-Snapshots
- `bot_comments` — Öffentliche Bot-Kommentare
- `bot_limits_state` — Cooldown/Rate-Limit Tracking

### DB-Zugriff
```bash
docker exec -i trading-postgres psql -U trading -d trading_v2
```

---

## Scoreboard API v2

**Port 8020** → `api-v2.quantarena.de`

### Endpoints

| Endpoint | Beschreibung |
|---|---|
| `GET /season` | Alle 10 Bots: Equity, Return%, PnL, Trades, Win Rate, Team, Archetype, Rank |
| `GET /teams` | Team-Standings: Gesamt-Equity pro Team, enthaltene Bots |
| `GET /equity?limit=150` | Equity-Zeitreihen pro Bot (für Charts) |
| `GET /orders?limit=50` | Letzte Orders aller Bots |
| `GET /trades?limit=30` | Letzte ausgeführte Trades |
| `GET /comments?limit=20` | Letzte Bot-Kommentare |
| `GET /health` | Healthcheck |

### Season-Response Format
```json
[
  {
    "bot_name": "MONO_APEX",
    "team": "MONO",
    "archetype": "APEX",
    "equity": 412500.00,
    "return_pct": 23.75,
    "pnl_realized": 79167.00,
    "trades": 142,
    "win_rate": 62.5,
    "rank": 1
  },
  ...
]
```

---

## Frontend v2

### Tech Stack
- React + Vite 6
- Framer Motion
- Inline Styles
- **Aktuell: Komplett auf Mock-Daten** (kein API-Polling)

### Source & Build
- **Source:** `/home/coob/quantarena-v2-src/`
- **Dist:** `/home/coob/quantarena-v2/dist/` → served via Caddy auf `v2.quantarena.de`
- **Build:** `cd /home/coob/quantarena-v2-src && npm run build`

### Komponenten

| Datei | Funktion |
|---|---|
| `App.jsx` | Hauptrouter: GateScreen → ArenaRing + Scoreboard + BattleFeed |
| `GateScreen.jsx` | Einstiegsseite |
| `ArenaRing.jsx` | Zentrale Arena-Ansicht — CONSENSUS in der Mitte, 9 Bots drumherum |
| `BotCard.jsx` | Einzelne Bot-Karte mit Portrait, Frame, Team-Farbe, Stats |
| `Scoreboard.jsx` | Detailliertes Ranking aller 9 Bots (CONSENSUS + VEIL rausgefiltert, neu nummeriert) |
| `BattleFeed.jsx` | Live-Feed der letzten Trades |
| `GateScreen.backup.jsx` | Backup der alten Gate-Version |

### Data Layer

#### Mock-Daten (`/src/data/mockData.js`)
- `TEAMS` — Team-Definitionen mit Farben
- `ARCHETYPES` — Archetype-Labels und Glyphen
- `BOTS` — 9 Bot-Definitionen mit Mock-Equity
- `getRankedBots()` — Sortiert nach Equity
- `getTeamStandings()` — Team-Gesamtequity
- `MOCK_FEED` — Mock-Trade-Feed

#### useArenaData Hook (`/src/hooks/useArenaData.js`)
- **Komplett auf Mock-Daten umgestellt** (kein API-Polling!)
- Mock-Daten direkt im Hook eingebaut
- Wird auf API umgestellt wenn Backend wieder läuft

### Assets (`/public/assets/`)
- `frame_global.png` (= `portraitrahmen.png`) — Portrait-Rahmen für alle Bots
- `portrait_apex.png` — APEX Archetype Portrait
- `portrait_macro.png` — MACRO Archetype Portrait
- `portrait_sentinel.png` — SENTINEL Archetype Portrait
- `sigil_core.png` — CORE Team Sigil
- `sigil_mono.png` — MONO Team Sigil
- `sigil_prism.png` — PRISM Team Sigil

### BotCard Styling
- Portrait mit `mix-blend-mode: multiply` (weißer Hintergrund verschwindet)
- Frame über Portrait (z-index)
- Dunkler Card-Hintergrund
- Team-Farbe als Akzent

### Visuelles Design
- Dunkle Arena-Ästhetik (wie v1)
- 3 Team-Farben: Rot (CORE), Blau (MONO), Grün (PRISM)
- Gold für VEIL/CONSENSUS
- Ring-Layout: CONSENSUS zentral, 9 Bots im Kreis

---

## Systemd Services (v2)

Alle Services aktuell **gestoppt** (bewusst für UI-Entwicklung):

```bash
# Alle v2 Services starten
sudo systemctl start \
  trading-v2-overseer \
  trading-v2-datahub \
  trading-v2-scoreboard \
  trading-v2-bot-core_apex \
  trading-v2-bot-core_macro \
  trading-v2-bot-core_sentinel \
  trading-v2-bot-mono_apex \
  trading-v2-bot-mono_macro \
  trading-v2-bot-mono_sentinel \
  trading-v2-bot-prism_apex \
  trading-v2-bot-prism_macro \
  trading-v2-bot-prism_sentinel \
  trading-v2-bot-consensus

# Status prüfen
sudo systemctl is-active trading-v2-overseer trading-v2-datahub trading-v2-scoreboard

# Logs
journalctl -u trading-v2-bot-core_apex -o cat -n 20 --no-pager
```

### Service-Konfiguration
- Jeder Bot-Service setzt Environment-Variablen: `BOT_NAME`, `BOT_TEAM`, `BOT_ARCHETYPE`
- Alle nutzen `/opt/trading/.venv/bin/python`
- Environment-Datei: `/opt/trading-v2/.env` (API Keys)

---

## Caddy-Konfiguration (v2)

```
v2.quantarena.de {
  root * /home/coob/quantarena-v2/dist
  file_server
  try_files {path} /index.html
}

api-v2.quantarena.de {
  reverse_proxy 127.0.0.1:8020
}
```

---

## Unterschiede v1 vs v2

| Aspekt | v1 | v2 |
|---|---|---|
| Bots | 3 (APEX, MACRO, SINGULARITY) | 9 + CONSENSUS = 10 |
| Teams | Keine | 3 Teams (CORE, MONO, PRISM) + VEIL |
| Archetypes | Jeder Bot einzigartig | 3x3 Matrix (Team x Archetype) |
| Reasoning | 4-Phasen Engine (Analyze→Strategize→Execute→Reflect) | Single LLM Call |
| Strategy Memory | Persistente JSON-Dateien | Keine (stateless) |
| Risk Limits | Arena-Modus (quasi keine) | Striktere Limits pro Bot-Typ |
| Cycle | 5 Minuten | 3 Minuten |
| Consensus | — | Majority-Vote (5/9) |
| DB | trading | trading_v2 |
| Frontend | Arena-Stage mit Podium | Ring-Layout mit CONSENSUS in Mitte |

---

## Offene Aufgaben / Nächste Schritte

### Frontend
- [ ] Portraits weißer Hintergrund optimieren (mix-blend-mode nicht perfekt)
- [ ] GateScreen v2 überarbeiten
- [ ] EquityChart für v2 bauen
- [ ] Düstere Optik verbessern (zu hell aktuell)
- [ ] Mobile Optimierung
- [ ] Team-Standings visuell darstellen

### Backend
- [ ] Backend wieder starten wenn Frontend fertig
- [ ] API an Frontend anbinden (useArenaData von Mock auf Real umstellen)
- [ ] Strategy Memory für v2 Bots einführen (wie v1 Reasoning Engine)
- [ ] Fill Simulator für v2

### Features
- [ ] Sound-Cues bei Trades/Ranking-Shifts
- [ ] Visuelle Trade-Manifestation
- [ ] Season-End Mechanik
- [ ] Live-Ticker
