# goldspanlabs/optopsy architecture

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

- Interactive diagram: https://gitdiagram.com/goldspanlabs/optopsy
- Repository: https://github.com/goldspanlabs/optopsy

## Overview

Optopsy is an options-strategy backtesting library, with companion market-data management and a Chainlit chat interface. The principal workflow loads option-chain data, constructs strategy trades, and returns performance statistics; simulation extends trade generation with chronological position and capital tracking. The graph also retains documented signal filtering, risk metrics, provider-backed data, and portfolio simulation. Several source excerpts are partial or absent, so UI tool wiring and some internal call relationships are intentionally not asserted.

Main entry points: [`optopsy/strategies`](https://github.com/goldspanlabs/optopsy/tree/main/optopsy/strategies) (Strategy catalog), [`optopsy/simulator.py`](https://github.com/goldspanlabs/optopsy/blob/main/optopsy/simulator.py) (Trade simulator), [`optopsy/evaluation.py`](https://github.com/goldspanlabs/optopsy/blob/main/optopsy/evaluation.py) (Trade evaluation), [`optopsy/data/providers/eodhd.py`](https://github.com/goldspanlabs/optopsy/blob/main/optopsy/data/providers/eodhd.py) (EODHD provider)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_backtest["Backtesting"]
  node_data_loading["Data loading<br/>[datafeeds.py]"]
  node_strategy_catalog["Strategy catalog"]
  node_evaluation["Trade evaluation<br/>[evaluation.py]"]
  node_entry_signals["Entry signals"]
  node_filters_rules["Filters and rules<br/>[filters.py]"]
  node_result_output["Result output<br/>[output.py]"]
end

subgraph group_simulation["Simulation and analytics"]
  node_trade_simulator["Trade simulator<br/>[simulator.py]"]
  node_early_exits["Early exits<br/>[exits.py]"]
  node_risk_metrics["Risk metrics<br/>[metrics.py]"]
  node_portfolio_sim["Portfolio simulation<br/>[simulator.py]"]
end

subgraph group_market_data["Market data"]
  node_data_cli["Data CLI<br/>[cli.py]"]
  node_provider_registry["Provider registry"]
  node_eodhd_provider["EODHD provider<br/>[eodhd.py]"]
  node_local_cache[("Local cache<br/>[cache.py]")]
end

subgraph group_chat["Chat interface"]
  node_chat_app["Chat application<br/>[app.py]"]
  node_chat_agent["Chat agent<br/>[agent.py]"]
  node_chat_tools["Analysis tools"]
  node_result_store[("Saved results<br/>[result_store.py]")]
end

node_researcher(("Researcher"))
node_chain_data["Option-chain data"]
node_eodhd_service["EODHD service"]

node_researcher -->|"loads data"| node_data_loading
node_chain_data -->|"provides input"| node_data_loading
node_data_loading -->|"supplies data"| node_strategy_catalog
node_researcher -->|"selects strategy"| node_strategy_catalog
node_strategy_catalog -->|"evaluates trades"| node_evaluation
node_entry_signals -->|"filters entries"| node_evaluation
node_evaluation -->|"applies criteria"| node_filters_rules
node_evaluation -->|"returns results"| node_result_output
node_researcher -->|"requests simulation"| node_trade_simulator
node_trade_simulator -->|"generates trades"| node_strategy_catalog
node_trade_simulator -->|"applies exit rules"| node_early_exits
node_trade_simulator -->|"computes metrics"| node_risk_metrics
node_researcher -->|"requests portfolio run"| node_portfolio_sim
node_portfolio_sim -->|"runs strategy legs"| node_strategy_catalog
node_researcher -->|"manages market data"| node_data_cli
node_data_cli -->|"uses providers"| node_provider_registry
node_provider_registry -->|"loads provider"| node_eodhd_provider
node_eodhd_provider -->|"fetches market data"| node_eodhd_service
node_eodhd_provider -->|"reads and writes"| node_local_cache
node_researcher -->|"starts chat"| node_chat_app
node_chat_app -->|"creates agent"| node_chat_agent
node_chat_agent -->|"dispatches requests"| node_chat_tools
node_chat_tools -->|"manages results"| node_result_store

click node_data_loading "https://github.com/goldspanlabs/optopsy/blob/main/optopsy/datafeeds.py"
click node_strategy_catalog "https://github.com/goldspanlabs/optopsy/tree/main/optopsy/strategies"
click node_evaluation "https://github.com/goldspanlabs/optopsy/blob/main/optopsy/evaluation.py"
click node_entry_signals "https://github.com/goldspanlabs/optopsy/tree/main/optopsy/signals"
click node_filters_rules "https://github.com/goldspanlabs/optopsy/blob/main/optopsy/filters.py"
click node_result_output "https://github.com/goldspanlabs/optopsy/blob/main/optopsy/output.py"
click node_trade_simulator "https://github.com/goldspanlabs/optopsy/blob/main/optopsy/simulator.py"
click node_early_exits "https://github.com/goldspanlabs/optopsy/blob/main/optopsy/exits.py"
click node_risk_metrics "https://github.com/goldspanlabs/optopsy/blob/main/optopsy/metrics.py"
click node_portfolio_sim "https://github.com/goldspanlabs/optopsy/blob/main/optopsy/simulator.py"
click node_data_cli "https://github.com/goldspanlabs/optopsy/blob/main/optopsy/data/cli.py"
click node_provider_registry "https://github.com/goldspanlabs/optopsy/tree/main/optopsy/data/providers"
click node_eodhd_provider "https://github.com/goldspanlabs/optopsy/blob/main/optopsy/data/providers/eodhd.py"
click node_local_cache "https://github.com/goldspanlabs/optopsy/blob/main/optopsy/data/providers/cache.py"
click node_chat_app "https://github.com/goldspanlabs/optopsy/blob/main/optopsy/ui/app.py"
click node_chat_agent "https://github.com/goldspanlabs/optopsy/blob/main/optopsy/ui/agent.py"
click node_chat_tools "https://github.com/goldspanlabs/optopsy/tree/main/optopsy/ui/tools"
click node_result_store "https://github.com/goldspanlabs/optopsy/blob/main/optopsy/ui/providers/result_store.py"

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_data_loading,node_strategy_catalog,node_evaluation,node_entry_signals,node_filters_rules,node_result_output toneBlue
class node_trade_simulator,node_early_exits,node_risk_metrics,node_portfolio_sim toneAmber
class node_data_cli,node_provider_registry,node_eodhd_provider,node_local_cache toneMint
class node_chat_app,node_chat_agent,node_chat_tools,node_result_store toneRose
class node_researcher,node_chain_data,node_eodhd_service toneIndigo
```

## Components

### Backtesting

- [Data loading](https://github.com/goldspanlabs/optopsy/blob/main/optopsy/datafeeds.py): `optopsy/datafeeds.py`
- [Strategy catalog](https://github.com/goldspanlabs/optopsy/tree/main/optopsy/strategies): `optopsy/strategies`
- [Trade evaluation](https://github.com/goldspanlabs/optopsy/blob/main/optopsy/evaluation.py): `optopsy/evaluation.py`
- [Entry signals](https://github.com/goldspanlabs/optopsy/tree/main/optopsy/signals): `optopsy/signals`
- [Filters and rules](https://github.com/goldspanlabs/optopsy/blob/main/optopsy/filters.py): `optopsy/filters.py`
- [Result output](https://github.com/goldspanlabs/optopsy/blob/main/optopsy/output.py): `optopsy/output.py`

### Simulation and analytics

- [Trade simulator](https://github.com/goldspanlabs/optopsy/blob/main/optopsy/simulator.py): `optopsy/simulator.py`
- [Early exits](https://github.com/goldspanlabs/optopsy/blob/main/optopsy/exits.py): `optopsy/exits.py`
- [Risk metrics](https://github.com/goldspanlabs/optopsy/blob/main/optopsy/metrics.py): `optopsy/metrics.py`
- [Portfolio simulation](https://github.com/goldspanlabs/optopsy/blob/main/optopsy/simulator.py): `optopsy/simulator.py`

### Market data

- [Data CLI](https://github.com/goldspanlabs/optopsy/blob/main/optopsy/data/cli.py): `optopsy/data/cli.py`
- [Provider registry](https://github.com/goldspanlabs/optopsy/tree/main/optopsy/data/providers): `optopsy/data/providers`
- [EODHD provider](https://github.com/goldspanlabs/optopsy/blob/main/optopsy/data/providers/eodhd.py): `optopsy/data/providers/eodhd.py`
- [Local cache](https://github.com/goldspanlabs/optopsy/blob/main/optopsy/data/providers/cache.py): `optopsy/data/providers/cache.py`

### Chat interface

- [Chat application](https://github.com/goldspanlabs/optopsy/blob/main/optopsy/ui/app.py): `optopsy/ui/app.py`
- [Chat agent](https://github.com/goldspanlabs/optopsy/blob/main/optopsy/ui/agent.py): `optopsy/ui/agent.py`
- [Analysis tools](https://github.com/goldspanlabs/optopsy/tree/main/optopsy/ui/tools): `optopsy/ui/tools`
- [Saved results](https://github.com/goldspanlabs/optopsy/blob/main/optopsy/ui/providers/result_store.py): `optopsy/ui/providers/result_store.py`

### Other components

- **Researcher**
- **Option-chain data**
- **EODHD service**

## Connections

- Researcher → Data loading: loads data
- Option-chain data → Data loading: provides input
- Data loading → Strategy catalog: supplies data
- Researcher → Strategy catalog: selects strategy
- Strategy catalog → Trade evaluation: evaluates trades
- Entry signals → Trade evaluation: filters entries
- Trade evaluation → Filters and rules: applies criteria
- Trade evaluation → Result output: returns results
- Researcher → Trade simulator: requests simulation
- Trade simulator → Strategy catalog: generates trades
- Trade simulator → Early exits: applies exit rules
- Trade simulator → Risk metrics: computes metrics
- Researcher → Portfolio simulation: requests portfolio run
- Portfolio simulation → Strategy catalog: runs strategy legs
- Researcher → Data CLI: manages market data
- Data CLI → Provider registry: uses providers
- Provider registry → EODHD provider: loads provider
- EODHD provider → EODHD service: fetches market data
- EODHD provider → Local cache: reads and writes
- Researcher → Chat application: starts chat
- Chat application → Chat agent: creates agent
- Chat agent → Analysis tools: dispatches requests
- Analysis tools → Saved results: manages results