# GammaDesk

GammaDesk is an options-market analytics dashboard for TanukiTrade-style workflows built on a clean-room calculation engine. The MVP currently runs on deterministic mock ORATS-style data, with a server-side ORATS connector stub ready for live or delayed API wiring.

The product goal is to highlight the levels an active trader cares about:

- **GEX profile** by strike
- **HVL / gamma flip**
- **Call wall / call resistance**
- **Put wall / put support**
- **Selected-alone vs cumulative expiration views**
- **IV rank, IVx, expected move, and skew**
- **Symbol screener and presets**

This is analytics software only. It is not financial advice and it should not be treated as a standalone trading signal.

## Quick start

```bash
npm install
npm run dev
```

The development server runs the Express API and Vite frontend together.

Useful scripts:

```bash
npm run dev      # start local dev server
npm run build    # production build
npm run start    # run production server after build
npm run check    # TypeScript check
```

## Environment

Copy `.env.example` to `.env` when wiring real ORATS data:

```bash
cp .env.example .env
```

The ORATS key must stay server-side. Do not expose it through Vite `VITE_` variables or browser settings.

## Project layout

```text
client/
  src/
    components/        Reusable dashboard components and charts
    lib/               Formatting, API client, symbol/theme contexts
    pages/             Dashboard, Gamma Levels, Expiry Matrix, Screener, Settings

server/
  index.ts             Express server entrypoint
  routes.ts            API routes consumed by the frontend and NT8 connector
  marketData.ts        Mock ORATS-style data generation and gamma calculations
  oratsClient.ts       Future ORATS API client integration point

shared/
  schema.ts            Shared TypeScript types and Zod schemas

docs/
  architecture.md      Product architecture and data flow
  orats-field-map.md   ORATS field mapping and calculation plan
  implementation.md    Build roadmap and engineering notes
```

## Current API routes

```text
GET /api/symbols
GET /api/orats/status
GET /api/market/:symbol/summary
GET /api/market/:symbol/gex
GET /api/market/:symbol/expirations
GET /api/screener
```

These routes currently return mock data from `server/marketData.ts`. The route shape is intentionally stable so NinjaTrader, future TradingView adapters, and the frontend can keep the same contracts after ORATS is connected.

## ORATS integration path

The intended production path is:

1. Implement `server/oratsClient.ts` methods for ORATS strikes, summaries, monies implied, expirations, tickers, and IV rank.
2. Normalize ORATS rows into the shared GammaDesk model.
3. Feed normalized rows into the existing gamma engine.
4. Keep mock fallback available for demos and local development.
5. Add caching and rate-limit protection before using large screeners.

See `docs/orats-field-map.md` for exact field mapping.

## Gamma calculation convention

Default Tanuki-style clean-room convention:

```ts
callGex = +gamma * callOpenInterest * 100 * spot ** 2 * 0.01;
putGex  = -gamma * putOpenInterest  * 100 * spot ** 2 * 0.01;
netGex  = callGex + putGex;
```

The sign convention should remain configurable internally because public vendors differ in dealer-positioning assumptions and TanukiTrade does not publicly disclose its proprietary formula.

## Related deliverables

- NinjaTrader 8 indicator package: `gammadesk-ninjatrader8`
- ORATS integration field-mapping spec: `docs/orats-field-map.md`