# Uforia Overview

`uforia` is a research-first trading platform scaffold.

Current platform pieces:
- Python analytics package under `src/uforia`
- versioned Parquet storage and manifests
- TimescaleDB serving/query layer for hot API/UI/training reads
- Deribit ingestion for BTC/ETH options and `DVOL`
- BTC/ETH VVIX analytics (`rVVIX`, `qVVIX`, `BVIX`)
- BTC/ETH Razor analytics (`razor_pnl`, `razor_vrp`, z-scores, trade bands)
- BTC/ETH options analytics family:
  - Vol Surface
  - Carry / VRP
  - Skew / Crash Premium
  - Surface Dislocation
  - Cross-Asset Relative Value
  - Positioning / Flow
  - Vol Cone
  - Term Structure Momentum
  - Gamma Exposure
  - Funding Context
  - Straddle Breakeven
  - Vol Regime Transitions
  - Surface Factor RV
  - ML Carry Toxicity
  - Expiry Flow Map
  - Adaptive Hedging
  - Sessionality Clocks
  - BTC-ETH Dispersion
  - Funding-Basis Skew
- BTC/ETH perps analytics family:
  - Funding-Basis Carry
  - Liquidation Cascade Risk
  - Order Flow Toxicity
  - OI-Price Divergence
  - Cross-Venue Price Discovery
  - Depth Resilience & Spread Regime
  - Volatility Microstructure
  - Cumulative Delta Momentum
- perps composite scores:
  - `carry_score`
  - `cascade_risk_score`
  - `toxicity_score`
  - `positioning_score`
  - `fragility_score`
- options composite scores:
  - `vol_carry_score`
  - `skew_stress_score`
  - `surface_dislocation_score`
  - `cross_asset_vol_score`
  - `vol_regime_score`
  - `funding_vol_context_score`
  - `breakeven_gap_score`
  - `term_structure_momentum_score`
  - `surface_factor_score`
  - `residual_surface_rv_score`
  - `ml_carry_toxicity_score`
  - `expiry_pin_score`
  - `gamma_flip_score`
  - `adaptive_hedge_score`
  - `sessionality_score`
  - `dispersion_score`
  - `funding_skew_score`
- composite market-state family:
  - `sentiment_index`
  - `directional_tilt`
  - `fragility_index`
  - `confidence_score`
  - BTC, ETH, and market-wide outputs
  - decomposition and transition views
- immutable run-aware options archiver
- Python read-only API for UI consumption
- Next.js internal research UI under `apps/web`
- medium-horizon microstructure family:
  - historical import from legacy `crypto-microstructure`
  - TCN-Boost tabular / TCN / fusion training, calibration, and export
  - microstructure API family
  - microstructure UI family
  - Rust live engine with Binance REST snapshot seeding and sequence validation
- execution family:
  - Rust execution adapters for Derive, Hyperliquid, Lighter, and Bebop
  - unified Python execution API and audit/state writes
  - execution datasets dual-written to Parquet + Timescale
  - thin operator UI for markets, order entry, orders, fills, positions, balances, and venue health
- repo-managed service runner scripts under `ops`
- Mac Mini `launchd` deployment for always-on collection and UI hosting

Current UI families:
- `Overview`: global health plus VVIX, Razor, and individual microstructure signal summaries
- `Signals`: VVIX, Razor, and individual microstructure prediction signals
- `Composite`: market-state overview, BTC, ETH, market, and decomposition pages
- `Options`: market-structure dashboards and options composite scores
- `Perps`: perp-market structure dashboards and perps composite scores
- `Microstructure`: model-specific views for predictions, regimes, features, calibration, backtests, and engine health
- `Execution`: venue-aware operator workflows and execution state

Current top-level layout:
- `src/uforia`: core analytics, ingestion, storage, signals, models, API service
- `apps/api`: thin Python API app wrapper
- `apps/web`: operator and research UI
- `tests`: Python integration and unit tests
- `docs`: project documentation

Design principles used so far:
- datasets are the stable platform contract
- analytics and ingestion write immutable runs
- Parquet is the immutable audit/recovery layer
- Timescale is the runtime serving/index layer for migrated datasets
- readers default to latest-by-primary-key views
- UI talks only to the API contract, never directly to storage
- market-structure dashboards are separated from headline signal families
- future Python tools and Rust engines plug into the same API and dataset interfaces
- production fixes are committed locally, pushed to Git, then pulled onto the Mac Mini
- signal families are asset-aware rather than BTC-only

Operational fixes already made:
- corrected DVOL ingestion units so Deribit index points are not multiplied by `100`
- fixed browser-side API and WebSocket host resolution for LAN access
- added WebSocket runtime support to the API environment
- widened API CORS policy to allow private-network browser origins
- tracked `ops/*.sh` in Git and marked them executable for `launchd`
