# gohnjalt/bubble-methodology architecture

> Architecture diagram of the GitHub repository gohnjalt/bubble-methodology, 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/gohnjalt/bubble-methodology
- Repository: https://github.com/gohnjalt/bubble-methodology

## Overview

Bubble Methodology turns market prices and inflation data into rolling bubble signals, then publishes a static dashboard for comparison across markets and trend windows. Its main workflow is data retrieval and caching, real-price construction, rolling-trend scoring, and site-data generation; a separate macro overlay adds context without changing the bubble signal. The repository also includes window-length evaluation and causal-filter studies. The README documents the dashboard capabilities; sampled excerpts do not show the full market registry or UI implementation, so those links are limited to documented behavior.

Main entry points: [`data.py`](https://github.com/gohnjalt/bubble-methodology/blob/main/data.py) (Market loader), [`filters.py`](https://github.com/gohnjalt/bubble-methodology/blob/main/filters.py) (Causal filter study), [`evaluate.py`](https://github.com/gohnjalt/bubble-methodology/blob/main/evaluate.py) (Window evaluation), [`bubble.py`](https://github.com/gohnjalt/bubble-methodology/blob/main/bubble.py) (Bubble model)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingestion["Data ingestion"]
  node_providers["Market data feeds"]
  node_loader["Market loader<br/>[data.py]"]
  node_cache[("Parquet cache<br/>[data.py]")]
end

subgraph group_signals["Signal models"]
  node_bubble["Bubble model<br/>[bubble.py]"]
  node_overlay["Macro overlay<br/>[overlay.py]"]
end

subgraph group_publishing["Dashboard"]
  node_builder["Site data builder<br/>[build.py]"]
  node_dashboard["Static dashboard<br/>[index.html]"]
end

subgraph group_research["Signal research"]
  node_evaluator["Window evaluation<br/>[evaluate.py]"]
  node_filters["Causal filter study<br/>[filters.py]"]
  node_results["Study tables"]
end

node_viewer(("Market viewer"))

node_providers -->|"supplies series"| node_loader
node_loader -->|"reads and refreshes"| node_cache
node_loader -->|"scores real prices"| node_bubble
node_loader -->|"builds macro score"| node_overlay
node_builder -->|"loads markets"| node_loader
node_builder -->|"writes dashboard data"| node_dashboard
node_viewer -->|"views signals"| node_dashboard
node_evaluator -->|"loads market data"| node_loader
node_evaluator -->|"tests windows"| node_bubble
node_evaluator -->|"writes study tables"| node_results
node_filters -->|"loads market data"| node_loader
node_filters -->|"uses baseline model"| node_bubble
node_filters -->|"uses return metric"| node_evaluator
node_filters -->|"writes filter tables"| node_results

click node_loader "https://github.com/gohnjalt/bubble-methodology/blob/main/data.py"
click node_cache "https://github.com/gohnjalt/bubble-methodology/blob/main/data.py"
click node_bubble "https://github.com/gohnjalt/bubble-methodology/blob/main/bubble.py"
click node_overlay "https://github.com/gohnjalt/bubble-methodology/blob/main/overlay.py"
click node_builder "https://github.com/gohnjalt/bubble-methodology/blob/main/build.py"
click node_dashboard "https://github.com/gohnjalt/bubble-methodology/blob/main/site/index.html"
click node_evaluator "https://github.com/gohnjalt/bubble-methodology/blob/main/evaluate.py"
click node_filters "https://github.com/gohnjalt/bubble-methodology/blob/main/filters.py"
click node_results "https://github.com/gohnjalt/bubble-methodology/tree/main/results"

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_providers,node_loader,node_cache,node_viewer toneBlue
class node_bubble,node_overlay toneAmber
class node_builder,node_dashboard toneMint
class node_evaluator,node_filters,node_results toneRose
```

## Components

### Data ingestion

- **Market data feeds**
- [Market loader](https://github.com/gohnjalt/bubble-methodology/blob/main/data.py): `data.py`
- [Parquet cache](https://github.com/gohnjalt/bubble-methodology/blob/main/data.py): `data.py`

### Signal models

- [Bubble model](https://github.com/gohnjalt/bubble-methodology/blob/main/bubble.py): `bubble.py`
- [Macro overlay](https://github.com/gohnjalt/bubble-methodology/blob/main/overlay.py): `overlay.py`

### Dashboard

- [Site data builder](https://github.com/gohnjalt/bubble-methodology/blob/main/build.py): `build.py`
- [Static dashboard](https://github.com/gohnjalt/bubble-methodology/blob/main/site/index.html): `site/index.html`

### Signal research

- [Window evaluation](https://github.com/gohnjalt/bubble-methodology/blob/main/evaluate.py): `evaluate.py`
- [Causal filter study](https://github.com/gohnjalt/bubble-methodology/blob/main/filters.py): `filters.py`
- [Study tables](https://github.com/gohnjalt/bubble-methodology/tree/main/results): `results`

### Other components

- **Market viewer**

## Connections

- Market data feeds → Market loader: supplies series
- Market loader → Parquet cache: reads and refreshes
- Market loader → Bubble model: scores real prices
- Market loader → Macro overlay: builds macro score
- Site data builder → Market loader: loads markets
- Site data builder → Static dashboard: writes dashboard data
- Market viewer → Static dashboard: views signals
- Window evaluation → Market loader: loads market data
- Window evaluation → Bubble model: tests windows
- Window evaluation → Study tables: writes study tables
- Causal filter study → Market loader: loads market data
- Causal filter study → Bubble model: uses baseline model
- Causal filter study → Window evaluation: uses return metric
- Causal filter study → Study tables: writes filter tables