Vibe‑Finance – Intrinsic Volatility Dashboard

A full‑stack monorepo that streams live crypto price data, performs VMD‑based signal decomposition, and visualises the results with interactive Plotly charts, a 3‑D phase‑space attractor, a spectrogram, and a heat‑map calendar. It also includes alerting, export/share, historical playback, and AI‑generated daily narratives.

Table of Contents

• Project Overview
• Prerequisites
• Backend – FastAPI
• Frontend – Next.js (React + TypeScript)
• Running the Whole Stack
• Environment Variables
• Data & Storage
• Testing & Linting
• Known Issues / Gotchas
• License
• Quick Start (one‑liner)

---

Project Overview

• Live crypto stream – backend/crypto_stream.py connects to Binance WebSocket, buffers price ticks, and yields a NumPy array of the latest 500 samples.
• Signal processing – backend/vmd_nht_processor.py runs Variational Mode Decomposition (VMD), extracting Intrinsic Mode Functions (IMFs), instantaneous frequency (IF), and amplitude (IA).
• FastAPI server – backend/main.py exposes:
  • /stream (SSE) – sends Plotly JSON (viz_json) plus LLM‑features.
  • /api/alerts/* – CRUD for user alerts (WebSocket push).
  • /api/historical/*, /api/daily_volatility/*, /api/narrative – data & AI endpoints.
• Frontend – intrinsic-volatility-dashboard/app (Next.js) renders:
  • Main Plotly chart (PhaseSpace3D, VolatilityRadar).
  • Spectrogram (SpectrogramCanvas).
  • Heat‑map calendar (VolatilityCalendar).
  • Controls: asset selector, playback timeline, AI settings, export/share, alerts.

---

Prerequisites

Tool	Minimum version
Python	3.12+ (tested on 3.13)
Node.js	20.x (LTS)
npm	10.x
Git	any recent version
Virtual‑env	venv (built‑in)
OpenAI API key (optional, for AI narrative)	–
Binance public WebSocket – no auth needed	–

---

Backend – FastAPI

1. Create a virtual environment (run from the repo root):

   python -m venv .venv
   # PowerShell (Windows)
   .venv\Scripts\Activate.ps1
   # Bash (macOS/Linux)
   source .venv/bin/activate

2. Install dependencies

   pip install -r backend/requirements.txt

3. Run the server

   uvicorn main:app --reload --port 8000

   The server will start on http://127.0.0.1:8000.

   • /stream is the SSE endpoint consumed by the frontend.
   • Swagger UI is available at http://127.0.0.1:8000/docs.

4. Database

   • SQLite file vibe_finance.db is created automatically on first run.
   • Tables: market_snapshots, alert_rules, alert_history, daily_summaries.

---

Frontend – Next.js (React + TypeScript)

1. Install node modules

   cd intrinsic-volatility-dashboard
   npm install

2. Start the dev server

   npm run dev

   The app will be served at http://localhost:3000.

3. Important components

   • app/components/StreamingDashboard.tsx – core page, connects to /stream via EventSource.
   • PhaseSpace3D.tsx – Plotly 3‑D scatter (IMF 2/3/4).
   • SpectrogramCanvas.tsx – Canvas‑based heat‑map built from IF/IA data.
   • VolatilityCalendar.tsx – D3 heat‑map of 90‑day volatility.
   • Utilities: AlertManager.tsx, ExportButton.tsx, LLMSettings.tsx.

4. Styling

   • Tailwind CSS + Shadcn UI utilities are pre‑configured (tailwind.config.js).
   • Global glass‑morphism styles live in app/globals.css.

---

Running the Whole Stack

# Terminal 1 – Backend
.venv\Scripts\Activate.ps1   # or source .venv/bin/activate
uvicorn main:app --reload --port 8000

# Terminal 2 – Frontend
cd intrinsic-volatility-dashboard
npm run dev

Open http://localhost:3000 in a browser. The dashboard should automatically connect to the SSE stream, display the live price line, the IMF traces, the 3‑D phase‑space, and the spectrogram.

---

Environment Variables

Create a .env file in the repo root (or set variables in your shell). Only the AI endpoint needs a key.

# OpenAI (optional – used by /api/narrative)
OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxx

# FastAPI secret (optional, for future auth)
FASTAPI_SECRET=your-secret-here

The backend reads these via os.getenv.

---

Data & Storage

• Live price buffer – in‑memory, 500‑sample circular buffer.
• Snapshots – persisted to SQLite every SNAPSHOT_INTERVAL seconds (default 10 s).
• Narratives – cached in daily_summaries table; subsequent calls return the stored text.

---

Testing & Linting

The repo includes minimal test scaffolding. To run linting:

# Backend
pip install flake8
flake8 backend

# Frontend
npm run lint   # uses eslint + prettier (already configured)

Add unit tests under backend/tests/ and intrinsic-volatility-dashboard/__tests__/ as needed.

---

Known Issues / Gotchas

• Trend line (IMF 1) appearing flat – ensure the VMD processor is receiving enough samples (len(signal) >= 100). The backend will skip processing until the buffer fills.
• Spectrogram/Phase‑Space not rendering – the frontend expects IF and IA traces named "IF X" / "IA X" (X = 1‑N). Do not hide them with visible='legendonly'.
• CORS – backend allows * origins for development; tighten in production.
• WebSocket alerts – only work while the backend is running; reconnect logic is in AlertManager.

---

License

This project is provided under the MIT License. See LICENSE for details.

---

Quick Start (one‑liner)

# Backend
python -m venv .venv && .venv\Scripts\Activate.ps1 && pip install -r backend/requirements.txt && uvicorn main:app --reload &
# Frontend (new terminal)
cd intrinsic-volatility-dashboard && npm install && npm run dev

Enjoy the live intrinsic volatility dashboard!