independent-reviewer

FinAlly — AI Trading Workstation

An AI-powered trading workstation with live market data, a simulated portfolio, and an LLM chat assistant that can analyze positions and execute trades. Looks and feels like a Bloomberg terminal with an AI copilot.

Built as a capstone project for an agentic AI coding course — the entire application is constructed by orchestrated AI coding agents.

---

Quick Start

# Copy and configure environment variables
cp .env.example .env
# Edit .env and add your OPENROUTER_API_KEY

# macOS / Linux
./scripts/start_mac.sh

# Windows (PowerShell)
./scripts/start_windows.ps1

Open http://localhost:8000. No login required — you start with $10,000 in virtual cash and a live watchlist of 10 tickers.

---

Features

• Live price streaming — prices flash green/red on every tick via SSE
• Sparkline charts — mini price charts per ticker, accumulated from the live stream
• Simulated trading — instant market orders, no fees, fractional shares supported
• Portfolio heatmap — treemap sized by weight, colored by P&L
• P&L chart — total portfolio value over time
• AI chat assistant — natural language trading, portfolio analysis, watchlist management
• Dynamic watchlist — add/remove tickers manually or via the AI

---

Environment Variables

Variable	Required	Description
OPENROUTER_API_KEY	Yes	OpenRouter API key for LLM chat
MASSIVE_API_KEY	No	Polygon.io key for real market data (uses simulator if absent)
LLM_MOCK	No	Set true for deterministic mock LLM responses (testing/CI)

---

Architecture

Single Docker container on port 8000:

• Frontend — Next.js (TypeScript), built as a static export, served by FastAPI
• Backend — FastAPI (Python/uv), handles all API routes, SSE streaming, DB, and LLM calls
• Database — SQLite, auto-initialized on first start, persisted via Docker volume
• Market data — GBM simulator by default; Polygon.io REST polling when MASSIVE_API_KEY is set
• AI — LiteLLM → OpenRouter (Cerebras inference), structured JSON outputs for trade execution

GET /api/stream/prices    SSE — live price updates
GET/POST /api/portfolio   Positions, cash, P&L, trade execution
GET/POST /api/watchlist   Watchlist management
POST /api/chat            AI assistant (message + auto-executed trades)

---

Development

# Backend (Python/uv)
cd backend
uv sync
uv run uvicorn app.main:app --reload --port 8000

# Market data demo (terminal dashboard)
uv run market_data_demo.py

# Tests
uv run pytest

# Frontend (Next.js)
cd frontend
npm install
npm run dev

---

Project Documentation

See planning/PLAN.md for the full project specification, API reference, database schema, LLM integration details, and testing strategy.