# chrislernunes/nautilus architecture

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

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

## Overview

1. **Overall shape**
   Nautilus is a local research platform, not a service backend. The main execution path is: market/macro data ingestion → feature engineering → 5-state HMM regime inference → signal generation/backtesting → Streamlit dashboard visualization and export.

2. **Primary entry point**
   The dashboard at `src/nautilus/dashboard/regime_dashboard.py` is the main application entry point. It orchestrates data loading, model fitting, signal calculation, plots, tables, and CSV exports in one interactive Streamlit UI.

3. **Data sources and persistence boundaries**
   The system combines:
   - Nifty 50 and US market series from `yfinance`
   - Bundled local CSVs for India 10Y yield and RBI repo rate
   - Local Parquet cache under `data/cache/` for downloaded/processed market data  
   This creates a clear split between external data acquisition and repeatable local analysis.

4. **ETL layer**
   `src/nautilus/etl/loader.py` handles price download and caching, while `src/nautilus/etl/macro.py` builds the macro feature set. This layer is responsible for aligning heterogeneous series on a common trading calendar and preparing model-ready inputs.

5. **Macro feature engineering**
   The macro pipeline folds Indian rates and bond data into regime features such as yield changes, yield spread, RBI easing flags, and moving-average ratios. The README indicates the HMM consumes a wide feature vector: realized volatility, returns, vol-of-vol, drawdown, 10Y yield delta, spread, repo flag, and DMA ratio.

6. **Regime modeling subsystem**
   `src/nautilus/strategies/regime.py` is the core analytics module. It fits a 5-state Gaussian Hidden Markov Model using `hmmlearn`, produces posterior regime probabilities, assigns dominant states, and provides Markov forward forecasts. The states are interpreted as market regimes like Bull Quiet, Bull Volatile, Neutral, Stress, and Panic.

7. **Signal generation subsystem**
   `src/nautilus/strategies/momentum.py` provides the baseline directional signal logic, centered on moving-average / price-above-MA behavior. The regime strategy then overlays a hard gate on top of this base signal, reducing or zeroing exposure depending on the inferred HMM state.

8. **Backtest engine**
   `src/nautilus/backtests/engine.py` evaluates MA vs regime-filtered strategies, applies transaction costs, and computes equity curves and performance metrics. The tests in `tests/test_engine.py` indicate this module is treated as a distinct, testable computational boundary separate from the dashboard.

9. **Decision layering**
   The strategy stack has two levels of control:
   - a continuous “soft Kelly” style signal, smoothed with EWM(5)
   - a discrete hard regime gate shifted by one day to avoid look-ahead  
   This means the final backtest signal is not just a model output; it is the composition of momentum plus regime-based capital allocation.

10. **Dashboard visualization layer**
    The Streamlit app presents multiple synchronized panels: regime shading on price charts, posterior probability stacks, Markov forecast paths, macro panels, volatility and drawdown views, attribution tables, and backtest comparison charts. The dashboard is a read-only analytical layer over the model and backtest outputs rather than a separate computation engine.

11. **US macro overlay**
    The US monitor is a parallel data track within the same dashboard, using S&P 500, US 10Y–3M spread, and Fed Funds Rate. Its shared-x alignment and inversion shading are important because they show the repo is built for cross-market regime comparison, not just India-only analysis.

12. **Configuration and package boundaries**
    `src/nautilus/config.py` centralizes paths, tickers, and model defaults, while `src/nautilus/__init__.py` marks the package version. The package is organized by concern: ETL, strategies, backtests, dashboard, with data stored outside the code under `data/`.

13. **Operational model**
    This repository is designed for interactive research on a local machine. There is no evidence of a database, message bus, or server-side orchestration layer; the main operational dependencies are Streamlit for UI, Parquet/CSV on disk for storage, and external market data APIs for refreshes.

14. **What an architecture diagram should show**
    A good diagram would place external data sources on the left, the ETL/cache layer in the middle, then split into two downstream paths: (a) regime/model/signal/backtest computation and (b) Streamlit dashboard visualization/export. The shared dependency between those paths is the feature-engineered time series and regime outputs.

Main entry points: [`src/nautilus/dashboard/regime_dashboard.py`](https://github.com/chrislernunes/nautilus/blob/main/src/nautilus/dashboard/regime_dashboard.py) (Regime dashboard), [`src/nautilus/etl/loader.py`](https://github.com/chrislernunes/nautilus/blob/main/src/nautilus/etl/loader.py) (Market loader), [`src/nautilus/etl/macro.py`](https://github.com/chrislernunes/nautilus/blob/main/src/nautilus/etl/macro.py) (Macro features), [`src/nautilus/strategies/momentum.py`](https://github.com/chrislernunes/nautilus/blob/main/src/nautilus/strategies/momentum.py) (Momentum signal)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_external["External sources"]
  node_node_yfinance(("Market APIs<br/>external data"))
  node_node_local_macro_csv["Macro CSVs<br/>local inputs"]
  node_node_cache[("Parquet cache<br/>local cache")]
end

subgraph group_grp_core["Core analysis"]
  node_node_config["Config<br/>[config.py]"]
  node_node_loader["Market loader<br/>ETL download/cache<br/>[loader.py]"]
  node_node_macro["Macro features<br/>ETL feature build<br/>[macro.py]"]
  node_node_momentum["Momentum signal<br/>signal logic<br/>[momentum.py]"]
  node_node_regime["Regime model<br/>HMM analytics<br/>[regime.py]"]
  node_node_backtest["Backtest engine<br/>performance eval<br/>[engine.py]"]
  node_node_pkg["Package root<br/>[__init__.py]"]
  node_node_tests["Engine tests<br/>test boundary<br/>[test_engine.py]"]
end

subgraph group_grp_ui["Dashboard"]
  node_node_dashboard["Regime dashboard<br/>Streamlit app"]
  node_node_price_view["Price views<br/>dashboard panel"]
  node_node_prob_view["Probabilities<br/>dashboard panel"]
  node_node_macro_view["Macro views<br/>dashboard panel"]
  node_node_perf_view["Performance<br/>dashboard panel"]
end

node_node_yfinance -->|"market data"| node_node_loader
node_node_local_macro_csv -->|"macro inputs"| node_node_macro
node_node_cache -->|"cached data"| node_node_loader
node_node_config -->|"paths/defaults"| node_node_loader
node_node_config -->|"paths/defaults"| node_node_macro
node_node_loader -->|"aligned series"| node_node_macro
node_node_loader -->|"price series"| node_node_momentum
node_node_macro -->|"feature vector"| node_node_regime
node_node_macro -->|"macro panels"| node_node_dashboard
node_node_momentum -->|"base signal"| node_node_regime
node_node_regime -->|"state signal"| node_node_backtest
node_node_momentum -->|"baseline strategy"| node_node_backtest
node_node_backtest -->|"metrics/equity"| node_node_dashboard
node_node_regime -->|"regime outputs"| node_node_dashboard
node_node_momentum -->|"signals"| node_node_dashboard
node_node_dashboard -->|"renders"| node_node_price_view
node_node_dashboard -->|"renders"| node_node_prob_view
node_node_dashboard -->|"renders"| node_node_macro_view
node_node_dashboard -->|"renders"| node_node_perf_view
node_node_tests -.->|"validates"| node_node_backtest
node_node_pkg -->|"package boundary"| node_node_config

click node_node_local_macro_csv "https://github.com/chrislernunes/nautilus/blob/main/data/india_10y_yield.csv"
click node_node_cache "https://github.com/chrislernunes/nautilus/blob/main/data/cache/_caret_NSEI.parquet"
click node_node_config "https://github.com/chrislernunes/nautilus/blob/main/src/nautilus/config.py"
click node_node_loader "https://github.com/chrislernunes/nautilus/blob/main/src/nautilus/etl/loader.py"
click node_node_macro "https://github.com/chrislernunes/nautilus/blob/main/src/nautilus/etl/macro.py"
click node_node_momentum "https://github.com/chrislernunes/nautilus/blob/main/src/nautilus/strategies/momentum.py"
click node_node_regime "https://github.com/chrislernunes/nautilus/blob/main/src/nautilus/strategies/regime.py"
click node_node_backtest "https://github.com/chrislernunes/nautilus/blob/main/src/nautilus/backtests/engine.py"
click node_node_dashboard "https://github.com/chrislernunes/nautilus/blob/main/src/nautilus/dashboard/regime_dashboard.py"
click node_node_pkg "https://github.com/chrislernunes/nautilus/blob/main/src/nautilus/__init__.py"
click node_node_tests "https://github.com/chrislernunes/nautilus/blob/main/tests/test_engine.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_node_yfinance,node_node_local_macro_csv,node_node_cache toneBlue
class node_node_config,node_node_loader,node_node_macro,node_node_momentum,node_node_regime,node_node_backtest,node_node_pkg,node_node_tests toneAmber
class node_node_dashboard,node_node_price_view,node_node_prob_view,node_node_macro_view,node_node_perf_view toneMint
```

## Components

### External sources

Market and macro inputs pulled from APIs and bundled local CSV data.

- **Market APIs**: external data · Nifty 50 and US market series fetched from yfinance.
- [Macro CSVs](https://github.com/chrislernunes/nautilus/blob/main/data/india_10y_yield.csv): local inputs · Bundled India 10Y yield and RBI repo rate files. · `data/india_10y_yield.csv`
- [Parquet cache](https://github.com/chrislernunes/nautilus/blob/main/data/cache/_caret_NSEI.parquet): local cache · Repeatable cached market and macro data stored on disk. · `data/cache/_caret_NSEI.parquet`

### Core analysis

ETL, feature engineering, regime inference, signal logic, and backtesting.

- [Config](https://github.com/chrislernunes/nautilus/blob/main/src/nautilus/config.py): package config · Centralized paths, tickers, and defaults. · `src/nautilus/config.py`
- [Market loader](https://github.com/chrislernunes/nautilus/blob/main/src/nautilus/etl/loader.py): ETL download/cache · Downloads price data and manages local caching. · `src/nautilus/etl/loader.py`
- [Macro features](https://github.com/chrislernunes/nautilus/blob/main/src/nautilus/etl/macro.py): ETL feature build · Aligns macro series and engineers regime features. · `src/nautilus/etl/macro.py`
- [Momentum signal](https://github.com/chrislernunes/nautilus/blob/main/src/nautilus/strategies/momentum.py): signal logic · Baseline moving-average / price-above-MA directional signal. · `src/nautilus/strategies/momentum.py`
- [Regime model](https://github.com/chrislernunes/nautilus/blob/main/src/nautilus/strategies/regime.py): HMM analytics · Fits the 5-state Gaussian HMM and derives regime probabilities and forecasts. · `src/nautilus/strategies/regime.py`
- [Backtest engine](https://github.com/chrislernunes/nautilus/blob/main/src/nautilus/backtests/engine.py): performance eval · Runs MA vs regime-filtered strategies with costs and metrics. · `src/nautilus/backtests/engine.py`
- [Package root](https://github.com/chrislernunes/nautilus/blob/main/src/nautilus/__init__.py): package · Nautilus package boundary and version marker. · `src/nautilus/__init__.py`
- [Engine tests](https://github.com/chrislernunes/nautilus/blob/main/tests/test_engine.py): test boundary · Test coverage for the backtest engine as a separate computational unit. · `tests/test_engine.py`

### Dashboard

Interactive Streamlit analysis and export layer.

- [Regime dashboard](https://github.com/chrislernunes/nautilus/blob/main/src/nautilus/dashboard/regime_dashboard.py): Streamlit app · Main entry point coordinating model runs, charts, tables, and CSV export. · `src/nautilus/dashboard/regime_dashboard.py`
- **Price views**: dashboard panel · Regime shading and price-based chart panels.
- **Probabilities**: dashboard panel · Posterior state stacks and Markov forecast visualizations.
- **Macro views**: dashboard panel · Macro, volatility, drawdown, and cross-market comparison panels.
- **Performance**: dashboard panel · Backtest comparison charts and attribution tables.

## Connections

- Market APIs → Market loader: market data · External market series are fetched for ingestion.
- Macro CSVs → Macro features: macro inputs · Bundled CSVs supply India yield and repo series.
- Parquet cache → Market loader: cached data · Loader reads and writes local Parquet cache.
- Config → Market loader: paths/defaults · Config provides tickers, paths, and operational defaults.
- Config → Macro features: paths/defaults · Config supports feature-building inputs and conventions.
- Market loader → Macro features: aligned series · Loaded market data feeds feature engineering.
- Market loader → Momentum signal: price series · Momentum logic consumes cleaned price history.
- Macro features → Regime model: feature vector · Engineered macro and market features drive HMM inference.
- Macro features → Regime dashboard: macro panels · Dashboard renders macro outputs and comparison views.
- Momentum signal → Regime model: base signal · Regime logic overlays gating on top of momentum behavior.
- Regime model → Backtest engine: state signal · Dominant states and probabilities shape the trading regime filter.
- Momentum signal → Backtest engine: baseline strategy · Backtests compare the raw momentum benchmark.
- Backtest engine → Regime dashboard: metrics/equity · Performance outputs are visualized in the dashboard.
- Regime model → Regime dashboard: regime outputs · Posterior probabilities, forecasts, and state labels feed the UI.
- Momentum signal → Regime dashboard: signals · Signal series support charts and export.
- Regime dashboard → Price views: renders · Main app composes price and regime shading panels.
- Regime dashboard → Probabilities: renders · Main app composes posterior and forecast panels.
- Regime dashboard → Macro views: renders · Main app composes macro and cross-market panels.
- Regime dashboard → Performance: renders · Main app composes backtest comparison and attribution panels.
- Engine tests → Backtest engine: validates · Tests treat the engine as a distinct computational boundary.
- Package root → Config: package boundary · Package root anchors shared modules and versioning.
