# aman6012/z-score-mean-reversion architecture

> Architecture diagram of the GitHub repository aman6012/z-score-mean-reversion, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/aman6012/z-score-mean-reversion
- Repository: https://github.com/aman6012/z-score-mean-reversion

## Overview

The product is a daily factor-neutral mean-reversion equity backtest, plus a separate static dashboard that presents sample results. The primary workflow fetches Alpaca bars, prepares price and volume panels, builds residual-based signals, simulates positions and portfolio returns, then produces backtest results. The dashboard’s run control is only a demo calculation; README explicitly says it does not consume live backtest results. Source excerpts show the main orchestration and selected strategy internals; unsampled details are represented only where README documents them.

Main entry points: [`src/backtest.py`](https://github.com/aman6012/z-score-mean-reversion/blob/main/src/backtest.py) (Fetch bars), [`web/app.js`](https://github.com/aman6012/z-score-mean-reversion/blob/main/web/app.js) (Sample dashboard)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Market data"]
  node_fetch["Fetch bars<br/>[backtest.py]"]
  node_panel["Price-volume panel<br/>[backtest.py]"]
end

subgraph group_signals["Signal research"]
  node_returns["Daily returns<br/>[backtest.py]"]
  node_regression["Rolling regression<br/>[backtest.py]"]
  node_signals["Residual signals<br/>[backtest.py]"]
  node_entries["Entry and exit rules<br/>[backtest.py]"]
end

subgraph group_simulation["Portfolio simulation"]
  node_neutralize["Sector-neutral weights<br/>[backtest.py]"]
  node_positions["Position simulation<br/>[backtest.py]"]
  node_results["Portfolio results<br/>[backtest.py]"]
end

subgraph group_dashboard["Sample dashboard"]
  node_dashboard["Sample dashboard<br/>[app.js]"]
end

node_researcher(("Researcher"))
node_alpaca[("Alpaca bars")]

node_researcher -->|"runs"| node_fetch
node_fetch -->|"requests bars"| node_alpaca
node_fetch -->|"prepares"| node_panel
node_panel -->|"builds returns"| node_returns
node_returns -->|"fits factors"| node_regression
node_regression -->|"computes residuals"| node_signals
node_signals -.->|"generates candidates"| node_entries
node_entries -->|"assigns weights"| node_neutralize
node_neutralize -->|"returns weights"| node_positions
node_positions -->|"calculates returns"| node_results
node_researcher -->|"views sample"| node_dashboard

click node_fetch "https://github.com/aman6012/z-score-mean-reversion/blob/main/src/backtest.py"
click node_panel "https://github.com/aman6012/z-score-mean-reversion/blob/main/src/backtest.py"
click node_returns "https://github.com/aman6012/z-score-mean-reversion/blob/main/src/backtest.py"
click node_regression "https://github.com/aman6012/z-score-mean-reversion/blob/main/src/backtest.py"
click node_signals "https://github.com/aman6012/z-score-mean-reversion/blob/main/src/backtest.py"
click node_entries "https://github.com/aman6012/z-score-mean-reversion/blob/main/src/backtest.py"
click node_neutralize "https://github.com/aman6012/z-score-mean-reversion/blob/main/src/backtest.py"
click node_positions "https://github.com/aman6012/z-score-mean-reversion/blob/main/src/backtest.py"
click node_results "https://github.com/aman6012/z-score-mean-reversion/blob/main/src/backtest.py"
click node_dashboard "https://github.com/aman6012/z-score-mean-reversion/blob/main/web/app.js"

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_fetch,node_panel toneBlue
class node_returns,node_regression,node_signals,node_entries,node_alpaca toneAmber
class node_neutralize,node_positions,node_results toneMint
class node_dashboard toneRose
class node_researcher toneIndigo
```

## Components

### Market data

- [Fetch bars](https://github.com/aman6012/z-score-mean-reversion/blob/main/src/backtest.py): `src/backtest.py`
- [Price-volume panel](https://github.com/aman6012/z-score-mean-reversion/blob/main/src/backtest.py): `src/backtest.py`

### Signal research

- [Daily returns](https://github.com/aman6012/z-score-mean-reversion/blob/main/src/backtest.py): `src/backtest.py`
- [Rolling regression](https://github.com/aman6012/z-score-mean-reversion/blob/main/src/backtest.py): `src/backtest.py`
- [Residual signals](https://github.com/aman6012/z-score-mean-reversion/blob/main/src/backtest.py): `src/backtest.py`
- [Entry and exit rules](https://github.com/aman6012/z-score-mean-reversion/blob/main/src/backtest.py): `src/backtest.py`

### Portfolio simulation

- [Sector-neutral weights](https://github.com/aman6012/z-score-mean-reversion/blob/main/src/backtest.py): `src/backtest.py`
- [Position simulation](https://github.com/aman6012/z-score-mean-reversion/blob/main/src/backtest.py): `src/backtest.py`
- [Portfolio results](https://github.com/aman6012/z-score-mean-reversion/blob/main/src/backtest.py): `src/backtest.py`

### Sample dashboard

- [Sample dashboard](https://github.com/aman6012/z-score-mean-reversion/blob/main/web/app.js): `web/app.js`

### Other components

- **Researcher**
- **Alpaca bars**

## Connections

- Researcher → Fetch bars: runs (evidence: `README.md`)
- Fetch bars → Alpaca bars: requests bars (evidence: `src/backtest.py`)
- Fetch bars → Price-volume panel: prepares (evidence: `src/backtest.py`)
- Price-volume panel → Daily returns: builds returns (evidence: `src/backtest.py`)
- Daily returns → Rolling regression: fits factors (evidence: `src/backtest.py`)
- Rolling regression → Residual signals: computes residuals (evidence: `src/backtest.py`)
- Residual signals → Entry and exit rules: generates candidates (evidence: `README.md`)
- Entry and exit rules → Sector-neutral weights: assigns weights (evidence: `src/backtest.py`)
- Sector-neutral weights → Position simulation: returns weights (evidence: `src/backtest.py`)
- Position simulation → Portfolio results: calculates returns (evidence: `src/backtest.py`)
- Researcher → Sample dashboard: views sample (evidence: `README.md`)