# GammaDesk Architecture

## Product layers

GammaDesk has four main layers:

1. **Data ingestion**: ORATS option-chain, volatility, summary, and IV-rank data.
2. **Gamma engine**: Per-strike GEX, net GEX, walls, HVL/gamma flip, expiration aggregation, and screener metrics.
3. **API layer**: Stable JSON routes used by the React dashboard, NinjaTrader 8 indicator, and future charting adapters.
4. **User interfaces**: Web dashboard now, NinjaTrader indicator now, optional TradingView-style overlay later.

## Frontend flow

The React app uses TanStack Query to fetch from the Express routes:

- `Dashboard` pulls summary and GEX profile data.
- `Gamma Levels` focuses on strike-level GEX levels.
- `Expiry Matrix` shows selected-alone and cumulative expiration views.
- `Screener` ranks symbols by gamma regime, IV rank, and distance to walls.
- `Settings` explains ORATS configuration and keeps any typed key in React state only.

Hash routing is used through Wouter so the app works correctly after deployment.

## Backend flow

The backend currently serves deterministic mock data:

```text
routes.ts -> marketData.ts -> shared schema-shaped JSON
```

The future live path is:

```text
routes.ts -> oratsClient.ts -> ORATS API -> normalizer -> gamma engine -> shared schema-shaped JSON
```

The frontend should not need to change when ORATS is connected.

## Data contracts

Keep these contracts stable:

- `MarketSummary`
- `GexProfile`
- `ExpirationRow`
- `ScreenerRow`
- `SymbolMeta`

If ORATS adds fields, add them as optional fields rather than breaking the existing route shape.

## Chart integrations

NinjaTrader 8 and future adapters should consume GammaDesk’s own API instead of calling ORATS directly. This keeps API keys private, centralizes caching, and lets the server enforce the chosen GEX sign convention.