# chrislernunes/pluto architecture

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

- Interactive diagram: https://gitdiagram.com/chrislernunes/pluto
- Repository: https://github.com/chrislernunes/pluto

## Overview

1. **Repository role**
   - Pluto is a Python research backtesting platform centered on rule-based trading strategies.
   - Its architecture is organized around a single flow: market data in, strategy decisions out, executed trades recorded, then metrics and optimization consume the resulting tradebook.

2. **Top-level execution pipeline**
   - The main orchestration lives in `backtest/`, which coordinates strategy setup, simulation/backtest runs, and positional-vs-non-positional variants.
   - The backtest layer does not appear to contain strategy logic itself; it is the control plane that wires together data access, the engine, and strategy classes.

3. **Core execution engine**
   - `engine/` is the runtime boundary for trade execution and state management.
   - `engine/datainterface.py` likely abstracts how historical or live-like data is delivered to strategies.
   - `engine/ems.py` and `engine/ems_db.py` suggest two data/execution backends, with the README indicating a Redis-backed path versus a database-backed path depending on configuration.
   - This is the layer where entries, exits, position updates, and tradebook creation are centralized.

4. **Strategy boundary**
   - `strategies/` contains the actual trading rules, separated into:
     - `strategies/others/` for established research/backtest strategies,
     - `strategies/live/` for strategies shaped for live-like integration,
     - `strategies/wip/` for experimental or in-progress ideas.
   - Examples like `tbs`, `ut`, `spikesell`, `pbsar`, and `btst` indicate the repo is strategy-agnostic: each strategy plugs into the same engine interface but implements its own entry/exit logic and parameterization.

5. **Backtest and simulation variants**
   - `backtest/backtester.py`, `backtest/backtester_pos.py`, `backtest/sim.py`, `backtest/sim_new.py`, `backtest/sim_strat.py`, and `backtest/sim_strat_pos.py` indicate multiple execution modes.
   - The “pos” suffix strongly suggests a positional variant of the same simulation/backtesting flow.
   - The notebook `backtest/backtester.ipynb` is likely used for exploratory research and manual analysis rather than production execution.

6. **Configuration model**
   - `backtest/configs/*.json` stores parameter presets for different strategy families.
   - These configs are the main way the same engine/strategy stack is reused across experiments without changing code, which supports reproducibility and systematic sweeps.

7. **Metrics and tradebook analysis**
   - `metrics/` is a downstream analytics layer that consumes executed trades rather than raw candles.
   - `metrics/metrics.py`, `metrics/analyze_tradebooks.py`, and `metrics/margin_calc.py` compute performance and risk outputs such as PnL, drawdown, trade statistics, and margin-related measures.
   - This reflects the repo’s “tradebook-first” design: execution produces a tradebook, and all evaluation is derived from that artifact.

8. **Optimization and research automation**
   - `optimization/` contains parameter search and robustness tooling.
   - Files like `*_optimizer.py`, `walkforward_optimizer.py`, `ut_walkforward.py`, and `generate_reports.py` suggest grid search, walk-forward testing, and report generation.
   - `visualizer_generic.py` and strategy-specific visualizers indicate the optimization layer also turns numeric results into comparative research outputs.

9. **Shared utilities**
   - `utils/definitions.py`, `utils/sessions.py`, `utils/logging_config.py`, and `utils/utility.py` provide shared constants, session/time-window logic, logging setup, and helper functions.
   - These utilities are important architectural glue because strategy correctness depends heavily on trading sessions, weekday filters, and consistent parameter naming/UID generation.

10. **Testing and validation**
   - `tests/` contains notebooks and Python test files focused on engine behavior and specific strategy validation.
   - The presence of `validate_tbs.py` and strategy-specific tests suggests the repo emphasizes regression checks on execution semantics, not just unit tests for helpers.

11. **Important data flow for a diagram**
   - The typical flow is: configuration and utilities define a run, a strategy class produces signals, the engine executes them against historical data, the backtester/simulator records tradebook output, metrics analyze the tradebook, and optimization loops repeat this across parameter sets.
   - The key architectural boundary is between **strategy logic** and **execution/measurement**: strategies decide “what,” the engine handles “how,” and metrics/optimization handle “how well.”

12. **Technology and runtime shape**
   - The project is Python-based and research-oriented, with optional acceleration hinted by the README’s Cython note.
   - External state/storage is abstracted behind the engine layer, especially via the Redis vs database split, which matters for deployment diagrams because it changes the data source but not the strategy interface.

Main entry points: [`utils`](https://github.com/chrislernunes/pluto/tree/main/utils) (Shared utils), [`backtest/sim_strat.py`](https://github.com/chrislernunes/pluto/blob/main/backtest/sim_strat.py) (Strategy sim), [`backtest/backtester.py`](https://github.com/chrislernunes/pluto/blob/main/backtest/backtester.py) (Backtest run), [`engine/datainterface.py`](https://github.com/chrislernunes/pluto/blob/main/engine/datainterface.py) (Data interface)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_control["Control plane"]
  node_backtest_runner["Backtest run<br/>orchestrator<br/>[backtester.py]"]
  node_backtest_pos["Positional run<br/>orchestrator<br/>[backtester_pos.py]"]
  node_sim_core["Simulator<br/>simulation<br/>[sim.py]"]
  node_sim_new["New sim<br/>simulation<br/>[sim_new.py]"]
  node_sim_strat["Strategy sim<br/>simulation<br/>[sim_strat.py]"]
  node_sim_strat_pos["Pos sim<br/>simulation<br/>[sim_strat_pos.py]"]
  node_config_presets["Config presets<br/>json presets"]
end

subgraph group_runtime["Execution runtime"]
  node_data_interface["Data interface<br/>market data API<br/>[datainterface.py]"]
  node_ems_redis["EMS Redis<br/>execution backend<br/>[ems.py]"]
  node_ems_db["EMS DB<br/>execution backend<br/>[ems_db.py]"]
end

subgraph group_research["Research layer"]
  node_tradebook["Tradebook<br/>execution artifact"]
  node_metrics_layer["Metrics<br/>analytics<br/>[metrics.py]"]
  node_tradebook_analysis["Tradebook analysis<br/>analytics"]
  node_margin_calc["Margin calc<br/>analytics<br/>[margin_calc.py]"]
  node_optimizer_runner["Optimizer<br/>search runner"]
  node_walkforward["Walk-forward<br/>search method"]
  node_reports["Reports<br/>reporting"]
end

subgraph group_strategies_grp["Strategies"]
  node_strategies_others["Research strats<br/>strategy set"]
  node_strategies_live["Live strats<br/>strategy set"]
  node_strategies_wip["WIP strats<br/>strategy set"]
end

subgraph group_shared["Shared code"]
  node_shared_utils["Shared utils<br/>helpers"]
end

node_config_presets -->|"parameterize"| node_backtest_runner
node_config_presets -->|"sweep"| node_optimizer_runner
node_shared_utils -->|"support"| node_backtest_runner
node_shared_utils -->|"support"| node_strategies_others
node_shared_utils -->|"support"| node_strategies_live
node_shared_utils -->|"support"| node_strategies_wip
node_backtest_runner -->|"run"| node_sim_core
node_backtest_pos -->|"run"| node_sim_strat_pos
node_backtest_runner -->|"run"| node_sim_strat
node_sim_core -->|"read"| node_data_interface
node_sim_new -->|"read"| node_data_interface
node_sim_strat -->|"invoke"| node_strategies_others
node_sim_strat -->|"invoke"| node_strategies_live
node_sim_strat -->|"invoke"| node_strategies_wip
node_sim_strat_pos -->|"invoke"| node_strategies_others
node_data_interface -->|"backend"| node_ems_redis
node_data_interface -->|"backend"| node_ems_db
node_ems_redis -->|"record"| node_tradebook
node_ems_db -->|"record"| node_tradebook
node_tradebook -->|"analyze"| node_metrics_layer
node_tradebook -->|"analyze"| node_tradebook_analysis
node_tradebook -->|"analyze"| node_margin_calc
node_tradebook -->|"evaluate"| node_optimizer_runner
node_optimizer_runner -->|"validate"| node_walkforward
node_optimizer_runner -->|"publish"| node_reports

click node_backtest_runner "https://github.com/chrislernunes/pluto/blob/main/backtest/backtester.py"
click node_backtest_pos "https://github.com/chrislernunes/pluto/blob/main/backtest/backtester_pos.py"
click node_sim_core "https://github.com/chrislernunes/pluto/blob/main/backtest/sim.py"
click node_sim_new "https://github.com/chrislernunes/pluto/blob/main/backtest/sim_new.py"
click node_sim_strat "https://github.com/chrislernunes/pluto/blob/main/backtest/sim_strat.py"
click node_sim_strat_pos "https://github.com/chrislernunes/pluto/blob/main/backtest/sim_strat_pos.py"
click node_config_presets "https://github.com/chrislernunes/pluto/tree/main/backtest/configs"
click node_data_interface "https://github.com/chrislernunes/pluto/blob/main/engine/datainterface.py"
click node_ems_redis "https://github.com/chrislernunes/pluto/blob/main/engine/ems.py"
click node_ems_db "https://github.com/chrislernunes/pluto/blob/main/engine/ems_db.py"
click node_metrics_layer "https://github.com/chrislernunes/pluto/blob/main/metrics/metrics.py"
click node_tradebook_analysis "https://github.com/chrislernunes/pluto/blob/main/metrics/analyze_tradebooks.py"
click node_margin_calc "https://github.com/chrislernunes/pluto/blob/main/metrics/margin_calc.py"
click node_optimizer_runner "https://github.com/chrislernunes/pluto/blob/main/optimization/optimization_runner.py"
click node_walkforward "https://github.com/chrislernunes/pluto/blob/main/optimization/walkforward_optimizer.py"
click node_reports "https://github.com/chrislernunes/pluto/blob/main/optimization/generate_reports.py"
click node_strategies_others "https://github.com/chrislernunes/pluto/tree/main/strategies/others"
click node_strategies_live "https://github.com/chrislernunes/pluto/tree/main/strategies/live"
click node_strategies_wip "https://github.com/chrislernunes/pluto/tree/main/strategies/wip"
click node_shared_utils "https://github.com/chrislernunes/pluto/tree/main/utils"

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_backtest_runner,node_backtest_pos,node_sim_core,node_sim_new,node_sim_strat,node_sim_strat_pos,node_config_presets toneBlue
class node_data_interface,node_ems_redis,node_ems_db toneAmber
class node_tradebook,node_metrics_layer,node_tradebook_analysis,node_margin_calc,node_optimizer_runner,node_walkforward,node_reports toneMint
class node_strategies_others,node_strategies_live,node_strategies_wip toneRose
class node_shared_utils toneIndigo
```

## Components

### Control plane

Backtest orchestration, simulation variants, and configuration presets.

- [Backtest run](https://github.com/chrislernunes/pluto/blob/main/backtest/backtester.py): orchestrator · Coordinates strategy setup and backtest/simulation entry points. · `backtest/backtester.py`
- [Positional run](https://github.com/chrislernunes/pluto/blob/main/backtest/backtester_pos.py): orchestrator · Positional variant of the backtest flow. · `backtest/backtester_pos.py`
- [Simulator](https://github.com/chrislernunes/pluto/blob/main/backtest/sim.py): simulation · Core simulation path used by research runs. · `backtest/sim.py`
- [New sim](https://github.com/chrislernunes/pluto/blob/main/backtest/sim_new.py): simulation · Alternative simulation implementation. · `backtest/sim_new.py`
- [Strategy sim](https://github.com/chrislernunes/pluto/blob/main/backtest/sim_strat.py): simulation · Simulation wrapper that drives strategy execution. · `backtest/sim_strat.py`
- [Pos sim](https://github.com/chrislernunes/pluto/blob/main/backtest/sim_strat_pos.py): simulation · Positional simulation wrapper. · `backtest/sim_strat_pos.py`
- [Config presets](https://github.com/chrislernunes/pluto/tree/main/backtest/configs): json presets · Strategy parameter presets used to reproduce runs. · `backtest/configs`

### Execution runtime

Strategy interface and trade execution/state management.

- [Data interface](https://github.com/chrislernunes/pluto/blob/main/engine/datainterface.py): market data API · Abstracts how historical data is delivered to the engine. · `engine/datainterface.py`
- [EMS Redis](https://github.com/chrislernunes/pluto/blob/main/engine/ems.py): execution backend · Redis-backed execution/state path. · `engine/ems.py`
- [EMS DB](https://github.com/chrislernunes/pluto/blob/main/engine/ems_db.py): execution backend · Database-backed execution/state path. · `engine/ems_db.py`

### Research layer

Analytics and optimization built on executed tradebooks.

- **Tradebook**: execution artifact · Executed trades and position history consumed downstream.
- [Metrics](https://github.com/chrislernunes/pluto/blob/main/metrics/metrics.py): analytics · Performance, risk, and margin calculations on tradebooks. · `metrics/metrics.py`
- [Tradebook analysis](https://github.com/chrislernunes/pluto/blob/main/metrics/analyze_tradebooks.py): analytics · Aggregates and analyzes tradebooks. · `metrics/analyze_tradebooks.py`
- [Margin calc](https://github.com/chrislernunes/pluto/blob/main/metrics/margin_calc.py): analytics · Margin-related evaluation for executed trades. · `metrics/margin_calc.py`
- [Optimizer](https://github.com/chrislernunes/pluto/blob/main/optimization/optimization_runner.py): search runner · Coordinates parameter search and repeated experiments. · `optimization/optimization_runner.py`
- [Walk-forward](https://github.com/chrislernunes/pluto/blob/main/optimization/walkforward_optimizer.py): search method · Walk-forward optimization and validation flow. · `optimization/walkforward_optimizer.py`
- [Reports](https://github.com/chrislernunes/pluto/blob/main/optimization/generate_reports.py): reporting · Generates comparative research outputs and summaries. · `optimization/generate_reports.py`

### Strategies

Rule-based strategy implementations by maturity and deployment mode.

- [Research strats](https://github.com/chrislernunes/pluto/tree/main/strategies/others): strategy set · Established backtest strategies. · `strategies/others`
- [Live strats](https://github.com/chrislernunes/pluto/tree/main/strategies/live): strategy set · Strategies adapted for live-like integration. · `strategies/live`
- [WIP strats](https://github.com/chrislernunes/pluto/tree/main/strategies/wip): strategy set · Experimental or in-progress strategies. · `strategies/wip`

### Shared code

Cross-cutting helpers for sessions, logging, and definitions.

- [Shared utils](https://github.com/chrislernunes/pluto/tree/main/utils): helpers · Definitions, sessions, and logging utilities used across runs. · `utils`

## Connections

- Config presets → Backtest run: parameterize · Presets configure a run.
- Config presets → Optimizer: sweep · Optimization iterates over preset spaces.
- Shared utils → Backtest run: support · Shared helpers shape execution and naming.
- Shared utils → Research strats: support · Strategies depend on common session and definition logic.
- Shared utils → Live strats: support · Live strategies reuse shared helpers.
- Shared utils → WIP strats: support · Experimental strategies reuse shared helpers.
- Backtest run → Simulator: run · Backtest orchestration enters simulation.
- Positional run → Pos sim: run · Positional backtests use the positional simulator.
- Backtest run → Strategy sim: run · Strategy-driven backtests use the strategy simulator.
- Simulator → Data interface: read · Simulation consumes market data through the interface.
- New sim → Data interface: read · Alternative simulation reads through the same boundary.
- Strategy sim → Research strats: invoke · Strategy simulation executes strategy logic.
- Strategy sim → Live strats: invoke · Strategy simulation can host live-shaped strategies.
- Strategy sim → WIP strats: invoke · Strategy simulation can host experimental strategies.
- Pos sim → Research strats: invoke · Positional strategy simulation executes strategy logic.
- Data interface → EMS Redis: backend · One execution/data path is Redis-backed.
- Data interface → EMS DB: backend · Another execution/data path is database-backed.
- EMS Redis → Tradebook: record · Executed actions are accumulated into a tradebook.
- EMS DB → Tradebook: record · Executed actions are accumulated into a tradebook.
- Tradebook → Metrics: analyze · Metrics are derived from executed trades.
- Tradebook → Tradebook analysis: analyze · Tradebook analysis consumes the same artifact.
- Tradebook → Margin calc: analyze · Margin calculations consume executed trade history.
- Tradebook → Optimizer: evaluate · Optimization compares parameter sets via tradebook results.
- Optimizer → Walk-forward: validate · Optimizer can invoke walk-forward validation.
- Optimizer → Reports: publish · Optimization produces reports and summaries.
