Claude/market data backend design mbnis2

.claude/agents/change-reviewer.md

@@ -0,0 +1,6 @@
+---
+name: change-reviewer
+description: carry out a comprehensive review of all changes since the last commit
+---
+
+You review the file planning/Plan.md and write your feedback to planning/review.md. 

.claude/agents/codex-reviewer.md

@@ -0,0 +1,6 @@
+---
+name: codex-reviewer
+description: carry out a comprehensive review of Plan.md when requested using codex
+---
+You are using a different ai agent to carry out a review of the document planning/Plan.md. you must execute the following shell commend to carry out the review - do not review yourself: 'codex exec "please review the file planning/plan.md and write your feedback to planning/review.md"'
+This will run the review process and save the result. Do not review yourself. 

.claude/agents/reviewer.md

@@ -0,0 +1,6 @@
+---
+name: Reviewer
+description: This custom agent reviews code and provides feedback on improvements, best practices, and potential issues.
+---
+
+You review the file planning/Plan.md and write your feedback to planning/review.md. 

.claude/commands/doc-review.md

@@ -0,0 +1 @@
+Review the documentation file in the planning folder called $ARGUMENTS and add questions, clarifications, or feedback toa new section at the end, along with any opportunities to simplify

.claude/settings.json

@@ -3,5 +3,17 @@
     "frontend-design@claude-plugins-official": true,
     "context7@claude-plugins-official": true,
     "playwright@claude-plugins-official": true
+  },
+  "hooks": {
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "if [ -z \"$FINALLY_STOP_HOOK_ACTIVE\" ]; then FINALLY_STOP_HOOK_ACTIVE=1 claude -p 'Use the change-reviewer agent to review all changes since the last commit and write the result to planning/review.md'; fi"
+          }
+        ]
+      }
+    ]
   }
 }

README.md

@@ -2,9 +2,22 @@
 
 A visually stunning AI-powered trading workstation that streams live market data, simulates portfolio trading, and integrates an LLM chat assistant that can analyze positions and execute trades via natural language.
 
-Built entirely by coding agents as a capstone project for an agentic AI coding course.
+Built entirely by coding agents as a capstone project for an agentic AI coding course. See [planning/PLAN.md](planning/PLAN.md) for the full spec.
 
-## Features
+## Status
+
+🚧 **Under active development.** Only the market data backend is built so far. The API routes, portfolio/trading logic, AI chat, frontend, and Docker packaging described below are planned but not yet implemented.
+
+**Done:**
+- ✅ Market data subsystem (`backend/app/market/`) — GBM simulator with correlated moves, Massive (Polygon.io) client, thread-safe price cache, SSE stream endpoint factory. 73 tests passing. See [planning/MARKET_DATA_SUMMARY.md](planning/MARKET_DATA_SUMMARY.md).
+
+**Not yet started:**
+- Database schema, portfolio/trade endpoints, watchlist endpoints
+- AI chat integration (LiteLLM → OpenRouter via Cerebras)
+- Frontend (Next.js terminal UI)
+- Dockerfile, start/stop scripts, E2E tests
+
+## Planned Features
 
 - **Live price streaming** via SSE with green/red flash animations
 - **Simulated portfolio** — $10k virtual cash, market orders, instant fills
@@ -13,48 +26,43 @@ Built entirely by coding agents as a capstone project for an agentic AI coding c
 - **Watchlist management** — track tickers manually or via AI
 - **Dark terminal aesthetic** — Bloomberg-inspired, data-dense layout
 
-## Architecture
+## Planned Architecture
 
 Single Docker container serving everything on port 8000:
 
 - **Frontend**: Next.js (static export) with TypeScript and Tailwind CSS
 - **Backend**: FastAPI (Python/uv) with SSE streaming
 - **Database**: SQLite with lazy initialization
 - **AI**: LiteLLM → OpenRouter (Cerebras inference) with structured outputs
-- **Market data**: Built-in GBM simulator (default) or Massive API (optional)
+- **Market data**: Built-in GBM simulator (default) or Massive API (optional) — ✅ implemented
 
-## Quick Start
+## Try the Market Data Demo
 
-```bash
-# Clone and configure
-cp .env.example .env
-# Add your OPENROUTER_API_KEY to .env
-
-# Run with Docker
-docker build -t finally .
-docker run -v finally-data:/app/db -p 8000:8000 --env-file .env finally
+The only runnable piece right now is a terminal demo of the market data simulator:
 
-# Open http://localhost:8000
+```bash
+cd backend
+uv sync
+uv run market_data_demo.py
 ```
 
+Displays a live-updating dashboard with all 10 tickers, sparklines, and an event log. Runs 60 seconds or until Ctrl+C.
+
 ## Environment Variables
 
 | Variable | Required | Description |
 |---|---|---|
-| `OPENROUTER_API_KEY` | Yes | OpenRouter API key for AI chat |
+| `OPENROUTER_API_KEY` | Yes (once chat is built) | OpenRouter API key for AI chat |
 | `MASSIVE_API_KEY` | No | Massive (Polygon.io) key for real market data; omit to use simulator |
 | `LLM_MOCK` | No | Set `true` for deterministic mock LLM responses (testing) |
 
 ## Project Structure
 
 ```
 finally/
-├── frontend/    # Next.js static export
-├── backend/     # FastAPI uv project
+├── backend/     # FastAPI uv project (market data subsystem built; API/DB/chat pending)
 ├── planning/    # Project documentation and agent contracts
-├── test/        # Playwright E2E tests
-├── db/          # SQLite volume mount (runtime)
-└── scripts/     # Start/stop helpers
+└── (planned)    frontend/, test/, db/, scripts/
 ```
 
 ## License