# madantv/ezoptions-schwab architecture

> Architecture diagram of the GitHub repository madantv/ezoptions-schwab, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/madantv/ezoptions-schwab
- Repository: https://github.com/madantv/ezoptions-schwab

## Overview

1. **Repository shape**
   - This is a **small, monolithic Python application** rather than a multi-service system.
   - The main runtime lives in **`ezoptionsschwab.py`**, with **`requirements.txt`** for dependencies and **`.env`** for Schwab credentials/configuration.
   - There are no separate frontend, worker, or backend service directories in the tree; the app likely bundles serving, data access, analytics, and rendering in one process.

2. **Primary runtime boundary**
   - The user interacts with the system through a **local browser dashboard** at **`http://localhost:5001`**.
   - The Python process acts as the central coordinator between:
     - the **browser UI**
     - the **Schwab API**
     - a local **SQLite** store for historical exposure data

3. **External market-data boundary: Schwab API**
   - Schwab is the main external integration and source of truth for live options data.
   - The app uses **OAuth-style API credentials** from environment variables:
     - `SCHWAB_APP_KEY`
     - `SCHWAB_APP_SECRET`
     - `SCHWAB_CALLBACK_URL`
   - This boundary is important architecturally because all live chain data, quotes, and refreshes depend on Schwab availability and API access.

4. **Data ingestion flow**
   - The dashboard accepts a ticker such as **SPY, SPX, or AAPL**, then retrieves:
     - options chain data
     - bid/ask/last prices
     - open interest / volume
     - implied volatility
     - underlying price updates
   - The app supports **auto-refresh / streaming-like updates** on a short interval, implying repeated polling rather than a separate streaming service.

5. **Analytics engine**
   - A core subsystem computes **options exposure metrics** from the live chain.
   - The README explicitly calls out:
     - **Gamma Exposure (GEX)**
     - **Delta Exposure (DEX)**
     - **Vanna Exposure**
     - **Charm, Speed, and Vomma**
   - These metrics are derived from the retrieved options data and then used to drive chart overlays, strike-level summaries, and historical tracking.

6. **Visualization / dashboard layer**
   - The UI is centered on **interactive charts and tables**:
     - real-time candlestick or **Heikin-Ashi** price charts
     - options chain table
     - exposure charts by strike
     - volume analysis
     - historical bubble charts
   - User controls affect the same data pipeline: expiration selection, strike-range filtering, exposure-weighting mode, chart toggles, and color settings.

7. **Historical persistence boundary: SQLite**
   - The only persistent datastore described is **SQLite**.
   - It stores **historical bubble-level data** at approximately **minute granularity**.
   - The database is initialized automatically and old data is cleaned up automatically, so persistence is intentionally narrow: it keeps recent exposure history, not the full market feed.

8. **Configuration and operational inputs**
   - Runtime behavior is driven by the `.env` file plus in-app controls.
   - Key config concepts exposed by the README:
     - multiple tickers
     - strike-range percentage filtering
     - call/put color customization
     - chart type toggles
     - auto-update enable/disable
     - exposure weighting by **Open Interest** or **Volume**
   - This suggests the app is highly stateful from the user’s perspective, but still single-process.

9. **Likely internal structure of `ezoptionsschwab.py`**
   - Since there is only one application file, the architecture is probably organized into logical sections inside that script:
     - Schwab authentication / client setup
     - data fetch and refresh logic
     - exposure calculations
     - SQLite read/write and cleanup
     - dashboard routes/endpoints and chart rendering
   - For an architecture diagram, it should be treated as a **modular monolith** even if the modules are not split into separate files.

10. **What matters most for a diagram**
   - Draw the system as a **local Python dashboard** in the center.
   - Show two external dependencies:
     - **Schwab API** for live market data
     - **SQLite** for stored historical exposure snapshots
   - Show the browser as the user-facing client, with data flowing from Schwab → analytics → UI, and a side path from analytics → SQLite for history.

11. **Scope and constraints**
   - This repo is focused on **informational/analytical trading visualization**, not order execution or portfolio management.
   - The README emphasizes educational use, which aligns with the absence of any brokerage execution subsystem in the repo layout.

Main entry points: [`ezoptionsschwab.py`](https://github.com/madantv/ezoptions-schwab/blob/main/ezoptionsschwab.py) (Main app), [`requirements.txt`](https://github.com/madantv/ezoptions-schwab/blob/main/requirements.txt) (Dependencies), [`.env`](https://github.com/madantv/ezoptions-schwab/blob/main/.env) (Env config)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client"]
  node_browser(("Browser<br/>local UI client"))
end

subgraph group_app["Python app"]
  node_app_main["Main app<br/>monolith<br/>[ezoptionsschwab.py]"]
  node_auth["Schwab auth<br/>oauth client<br/>[ezoptionsschwab.py]"]
  node_fetch["Market fetch<br/>polling ingest<br/>[ezoptionsschwab.py]"]
  node_refresh["Refresh loop<br/>update scheduler<br/>[ezoptionsschwab.py]"]
  node_analytics["Exposure engine<br/>options analytics<br/>[ezoptionsschwab.py]"]
  node_history["History store<br/>sqlite access<br/>[ezoptionsschwab.py]"]
  node_ui["Dashboard UI<br/>rendering layer<br/>[ezoptionsschwab.py]"]
  node_controls["User controls<br/>chart options<br/>[ezoptionsschwab.py]"]
end

subgraph group_external["External services"]
  node_schwab[("Schwab API<br/>market data service")]
  node_sqlite[("SQLite DB<br/>historical store")]
end

subgraph group_config["Config"]
  node_env["Env config<br/>runtime config<br/>[.env]"]
  node_deps["Dependencies<br/>python manifest<br/>[requirements.txt]"]
end

node_browser -->|"uses"| node_ui
node_app_main -->|"contains"| node_auth
node_app_main -->|"contains"| node_fetch
node_app_main -->|"contains"| node_refresh
node_app_main -->|"contains"| node_analytics
node_app_main -->|"contains"| node_history
node_app_main -->|"contains"| node_ui
node_ui -->|"exposes"| node_controls
node_controls -->|"drives"| node_fetch
node_controls -->|"drives"| node_analytics
node_refresh -->|"triggers"| node_fetch
node_fetch -->|"queries"| node_schwab
node_auth -->|"reads"| node_env
node_auth -->|"authorizes"| node_schwab
node_fetch -->|"feeds"| node_analytics
node_analytics -->|"renders"| node_ui
node_analytics -->|"persists"| node_history
node_history -->|"stores"| node_sqlite
node_deps -.->|"supports"| node_app_main

click node_app_main "https://github.com/madantv/ezoptions-schwab/blob/main/ezoptionsschwab.py"
click node_auth "https://github.com/madantv/ezoptions-schwab/blob/main/ezoptionsschwab.py"
click node_fetch "https://github.com/madantv/ezoptions-schwab/blob/main/ezoptionsschwab.py"
click node_refresh "https://github.com/madantv/ezoptions-schwab/blob/main/ezoptionsschwab.py"
click node_analytics "https://github.com/madantv/ezoptions-schwab/blob/main/ezoptionsschwab.py"
click node_history "https://github.com/madantv/ezoptions-schwab/blob/main/ezoptionsschwab.py"
click node_ui "https://github.com/madantv/ezoptions-schwab/blob/main/ezoptionsschwab.py"
click node_controls "https://github.com/madantv/ezoptions-schwab/blob/main/ezoptionsschwab.py"
click node_env "https://github.com/madantv/ezoptions-schwab/blob/main/.env"
click node_deps "https://github.com/madantv/ezoptions-schwab/blob/main/requirements.txt"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_browser toneBlue
class node_app_main,node_auth,node_fetch,node_refresh,node_analytics,node_history,node_ui,node_controls toneAmber
class node_schwab,node_sqlite toneMint
class node_env,node_deps toneRose
```

## Components

### Client

User-facing browser dashboard

- **Browser**: local UI client · User interacts through a local dashboard at localhost:5001

### Python app

Single-process monolithic runtime

- [Main app](https://github.com/madantv/ezoptions-schwab/blob/main/ezoptionsschwab.py): monolith · Single Python runtime coordinating data access, analytics, persistence, and rendering · `ezoptionsschwab.py`
- [Schwab auth](https://github.com/madantv/ezoptions-schwab/blob/main/ezoptionsschwab.py): oauth client · Builds authenticated Schwab access from environment credentials · `ezoptionsschwab.py`
- [Market fetch](https://github.com/madantv/ezoptions-schwab/blob/main/ezoptionsschwab.py): polling ingest · Pulls options chains, quotes, and underlying prices on refresh · `ezoptionsschwab.py`
- [Refresh loop](https://github.com/madantv/ezoptions-schwab/blob/main/ezoptionsschwab.py): update scheduler · Drives repeated auto-refresh and short-interval updates · `ezoptionsschwab.py`
- [Exposure engine](https://github.com/madantv/ezoptions-schwab/blob/main/ezoptionsschwab.py): options analytics · Computes GEX, DEX, Vanna, Charm, Speed, and Vomma from live chains · `ezoptionsschwab.py`
- [History store](https://github.com/madantv/ezoptions-schwab/blob/main/ezoptionsschwab.py): sqlite access · Writes and reads minute-level historical exposure snapshots · `ezoptionsschwab.py`
- [Dashboard UI](https://github.com/madantv/ezoptions-schwab/blob/main/ezoptionsschwab.py): rendering layer · Serves interactive charts, tables, and control state · `ezoptionsschwab.py`
- [User controls](https://github.com/madantv/ezoptions-schwab/blob/main/ezoptionsschwab.py): chart options · Ticker, expiration, strike range, weighting, and display toggles · `ezoptionsschwab.py`

### External services

Live market-data and persistence boundaries

- **Schwab API**: market data service · External source for live options data and quote refreshes
- **SQLite DB**: historical store · Local persistent store for exposure history

### Config

Runtime inputs and dependency manifest

- [Env config](https://github.com/madantv/ezoptions-schwab/blob/main/.env): runtime config · Provides Schwab credentials and app settings · `.env`
- [Dependencies](https://github.com/madantv/ezoptions-schwab/blob/main/requirements.txt): python manifest · Pinned Python packages used by the monolith · `requirements.txt`

## Connections

- Browser → Dashboard UI: uses · Browser requests and views the dashboard
- Main app → Schwab auth: contains · Main runtime includes Schwab client setup
- Main app → Market fetch: contains · Main runtime performs live market-data ingestion
- Main app → Refresh loop: contains · Main runtime schedules auto-refresh
- Main app → Exposure engine: contains · Main runtime computes options exposure metrics
- Main app → History store: contains · Main runtime manages SQLite persistence
- Main app → Dashboard UI: contains · Main runtime serves charts and tables
- Dashboard UI → User controls: exposes · Dashboard exposes interactive filtering and display controls
- User controls → Market fetch: drives · Ticker, strike range, and expiration affect data requests
- User controls → Exposure engine: drives · Weighting and chart settings affect derived views
- Refresh loop → Market fetch: triggers · Auto-update loop repeatedly polls for new data
- Market fetch → Schwab API: queries · Retrieves live chains, quotes, and underlying updates
- Schwab auth → Env config: reads · Uses Schwab app key, secret, and callback URL
- Schwab auth → Schwab API: authorizes · Creates authenticated API access
- Market fetch → Exposure engine: feeds · Live market data flows into exposure calculations
- Exposure engine → Dashboard UI: renders · Derived exposures drive charts, strike summaries, and overlays
- Exposure engine → History store: persists · Selected exposure snapshots are written for history tracking
- History store → SQLite DB: stores · Historical bubble-level data is stored locally
- Dependencies → Main app: supports · Package dependencies enable the monolithic app runtime
