gammanexus/docs/architecture.md

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:

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

The future live path is:

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.