# calvin4370/nhb-museum-visitorship-forecasting architecture

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

- Interactive diagram: https://gitdiagram.com/calvin4370/nhb-museum-visitorship-forecasting
- Repository: https://github.com/calvin4370/nhb-museum-visitorship-forecasting

## Overview

This repository forecasts monthly visitorship for five Singapore museums, fetching visitor and international-arrival series before preparing features, evaluating models, ranking them, and producing forecasts up to 24 months ahead. The README also documents saved-model regeneration, tuning reports, permutation importance, financial-year summaries, plots, and an IHC Deepavali analysis. The graph follows the documented and excerpted orchestration; connections to unsampled implementations are included only where the SOURCE INDEX or README supports them.

Main entry points: [`src/pipeline.py`](https://github.com/calvin4370/nhb-museum-visitorship-forecasting/blob/main/src/pipeline.py) (Museum pipeline), [`src/models/model_registry.py`](https://github.com/calvin4370/nhb-museum-visitorship-forecasting/blob/main/src/models/model_registry.py) (Model registry), [`main.py`](https://github.com/calvin4370/nhb-museum-visitorship-forecasting/blob/main/main.py) (CLI entry), [`src/data/singstat_api.py`](https://github.com/calvin4370/nhb-museum-visitorship-forecasting/blob/main/src/data/singstat_api.py) (SingStat client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_acquisition["Data and features"]
  node_singstat["SingStat client<br/>[singstat_api.py]"]
  node_raw_data["Raw series"]
  node_feature_prep["Feature engineering<br/>[data_prep.py]"]
  node_event_ranges["Event ranges<br/>[event_range.py]"]
  node_processed_data["Prepared data"]
end

subgraph group_forecasting["Forecasting"]
  node_registry["Model registry<br/>[model_registry.py]"]
  node_baseline["Baseline model<br/>[baseline.py]"]
  node_holtwinters["Holt-Winters<br/>[holtwinters.py]"]
  node_sarimax["SARIMAX<br/>[sarimax.py]"]
  node_randomforest["Random Forest<br/>[randomforest.py]"]
  node_xgboost["XGBoost<br/>[xgboost_model.py]"]
  node_svr["Support vector<br/>[svr.py]"]
  node_lstm["LSTM<br/>[lstm.py]"]
  node_timegpt["TimeGPT adapter<br/>[timegpt.py]"]
  node_fitted["Fitted model wrapper<br/>[fitted.py]"]
end

subgraph group_analysis["Analysis and reporting"]
  node_tuning[("Optuna persistence<br/>[tuning.py]")]
  node_artifacts["Model artifacts<br/>[artifacts.py]"]
  node_importance["Permutation importance<br/>[importance.py]"]
  node_feature_report["Importance report<br/>[feature_report.py]"]
  node_timeplot["Forecast plots<br/>[timeplot.py]"]
  node_alt_plots["Seaborn plots<br/>[jj_new_plots.py]"]
  node_summary["Museum summaries<br/>[summary.py]"]
  node_deepavali["Deepavali analysis<br/>[deepavali.py]"]
  node_tuning_report["Tuning report<br/>[tuning_report.py]"]
  node_outputs["Forecast outputs"]
end

subgraph group_runtime["Runtime orchestration"]
  node_entry["CLI entry<br/>[main.py]"]
  node_cli["Argument selection<br/>[cli.py]"]
  node_config["Forecast configuration<br/>[config.py]"]
  node_pipeline["Museum pipeline<br/>[pipeline.py]"]
end

node_operator(("Operator"))
node_singstat_service{{"SingStat API"}}

node_operator -->|"runs"| node_entry
node_entry -->|"parses options"| node_cli
node_entry -->|"fetches series"| node_singstat
node_entry -->|"runs museums"| node_pipeline
node_entry -->|"selects defaults"| node_config
node_singstat -->|"requests data"| node_singstat_service
node_singstat -->|"returns series"| node_raw_data
node_pipeline -->|"engineers features"| node_feature_prep
node_feature_prep -->|"loads occurrences"| node_event_ranges
node_pipeline -->|"saves features"| node_processed_data
node_pipeline -->|"selects models"| node_registry
node_registry -->|"dispatches"| node_baseline
node_registry -->|"dispatches"| node_holtwinters
node_registry -->|"dispatches"| node_sarimax
node_registry -->|"dispatches"| node_randomforest
node_registry -->|"dispatches"| node_xgboost
node_registry -->|"dispatches"| node_svr
node_registry -->|"dispatches"| node_lstm
node_registry -->|"dispatches"| node_timegpt
node_sarimax -->|"creates study"| node_tuning
node_holtwinters -->|"creates study"| node_tuning
node_pipeline -->|"saves models"| node_artifacts
node_pipeline -->|"computes importance"| node_importance
node_pipeline -->|"builds report"| node_feature_report
node_pipeline -->|"renders plots"| node_timeplot
node_pipeline -->|"renders plots"| node_alt_plots
node_pipeline -->|"writes summaries"| node_summary
node_pipeline -->|"builds analysis"| node_deepavali
node_pipeline -->|"writes report"| node_tuning_report
node_pipeline -->|"writes forecasts"| node_outputs
node_fitted -.->|"saved by"| node_artifacts
node_tuning_report -->|"loads studies"| node_tuning
node_summary -->|"includes table"| node_deepavali

click node_entry "https://github.com/calvin4370/nhb-museum-visitorship-forecasting/blob/main/main.py"
click node_cli "https://github.com/calvin4370/nhb-museum-visitorship-forecasting/blob/main/src/cli.py"
click node_config "https://github.com/calvin4370/nhb-museum-visitorship-forecasting/blob/main/config.py"
click node_singstat "https://github.com/calvin4370/nhb-museum-visitorship-forecasting/blob/main/src/data/singstat_api.py"
click node_raw_data "https://github.com/calvin4370/nhb-museum-visitorship-forecasting/tree/main/data/raw"
click node_feature_prep "https://github.com/calvin4370/nhb-museum-visitorship-forecasting/blob/main/src/features/data_prep.py"
click node_event_ranges "https://github.com/calvin4370/nhb-museum-visitorship-forecasting/blob/main/src/events/event_range.py"
click node_processed_data "https://github.com/calvin4370/nhb-museum-visitorship-forecasting/tree/main/data/processed"
click node_pipeline "https://github.com/calvin4370/nhb-museum-visitorship-forecasting/blob/main/src/pipeline.py"
click node_registry "https://github.com/calvin4370/nhb-museum-visitorship-forecasting/blob/main/src/models/model_registry.py"
click node_baseline "https://github.com/calvin4370/nhb-museum-visitorship-forecasting/blob/main/src/models/baseline.py"
click node_holtwinters "https://github.com/calvin4370/nhb-museum-visitorship-forecasting/blob/main/src/models/holtwinters.py"
click node_sarimax "https://github.com/calvin4370/nhb-museum-visitorship-forecasting/blob/main/src/models/sarimax.py"
click node_randomforest "https://github.com/calvin4370/nhb-museum-visitorship-forecasting/blob/main/src/models/randomforest.py"
click node_xgboost "https://github.com/calvin4370/nhb-museum-visitorship-forecasting/blob/main/src/models/xgboost_model.py"
click node_svr "https://github.com/calvin4370/nhb-museum-visitorship-forecasting/blob/main/src/models/svr.py"
click node_lstm "https://github.com/calvin4370/nhb-museum-visitorship-forecasting/blob/main/src/models/lstm.py"
click node_timegpt "https://github.com/calvin4370/nhb-museum-visitorship-forecasting/blob/main/src/models/timegpt.py"
click node_fitted "https://github.com/calvin4370/nhb-museum-visitorship-forecasting/blob/main/src/models/fitted.py"
click node_tuning "https://github.com/calvin4370/nhb-museum-visitorship-forecasting/blob/main/src/analysis/tuning.py"
click node_artifacts "https://github.com/calvin4370/nhb-museum-visitorship-forecasting/blob/main/src/analysis/artifacts.py"
click node_importance "https://github.com/calvin4370/nhb-museum-visitorship-forecasting/blob/main/src/analysis/importance.py"
click node_feature_report "https://github.com/calvin4370/nhb-museum-visitorship-forecasting/blob/main/src/visualisation/feature_report.py"
click node_timeplot "https://github.com/calvin4370/nhb-museum-visitorship-forecasting/blob/main/src/visualisation/timeplot.py"
click node_alt_plots "https://github.com/calvin4370/nhb-museum-visitorship-forecasting/blob/main/src/visualisation/jj_new_plots.py"
click node_summary "https://github.com/calvin4370/nhb-museum-visitorship-forecasting/blob/main/src/visualisation/summary.py"
click node_deepavali "https://github.com/calvin4370/nhb-museum-visitorship-forecasting/blob/main/src/analysis/deepavali.py"
click node_tuning_report "https://github.com/calvin4370/nhb-museum-visitorship-forecasting/blob/main/src/analysis/tuning_report.py"
click node_outputs "https://github.com/calvin4370/nhb-museum-visitorship-forecasting/tree/main/outputs"

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_singstat,node_raw_data,node_feature_prep,node_event_ranges,node_processed_data toneBlue
class node_registry,node_baseline,node_holtwinters,node_sarimax,node_randomforest,node_xgboost,node_svr,node_lstm,node_timegpt,node_fitted toneAmber
class node_tuning,node_artifacts,node_importance,node_feature_report,node_timeplot,node_alt_plots,node_summary,node_deepavali,node_tuning_report,node_outputs,node_singstat_service toneMint
class node_entry,node_cli,node_config,node_pipeline toneRose
class node_operator toneIndigo
```

## Components

### Data and features

- [SingStat client](https://github.com/calvin4370/nhb-museum-visitorship-forecasting/blob/main/src/data/singstat_api.py): `src/data/singstat_api.py`
- [Raw series](https://github.com/calvin4370/nhb-museum-visitorship-forecasting/tree/main/data/raw): `data/raw`
- [Feature engineering](https://github.com/calvin4370/nhb-museum-visitorship-forecasting/blob/main/src/features/data_prep.py): `src/features/data_prep.py`
- [Event ranges](https://github.com/calvin4370/nhb-museum-visitorship-forecasting/blob/main/src/events/event_range.py): `src/events/event_range.py`
- [Prepared data](https://github.com/calvin4370/nhb-museum-visitorship-forecasting/tree/main/data/processed): `data/processed`

### Forecasting

- [Model registry](https://github.com/calvin4370/nhb-museum-visitorship-forecasting/blob/main/src/models/model_registry.py): `src/models/model_registry.py`
- [Baseline model](https://github.com/calvin4370/nhb-museum-visitorship-forecasting/blob/main/src/models/baseline.py): `src/models/baseline.py`
- [Holt-Winters](https://github.com/calvin4370/nhb-museum-visitorship-forecasting/blob/main/src/models/holtwinters.py): `src/models/holtwinters.py`
- [SARIMAX](https://github.com/calvin4370/nhb-museum-visitorship-forecasting/blob/main/src/models/sarimax.py): `src/models/sarimax.py`
- [Random Forest](https://github.com/calvin4370/nhb-museum-visitorship-forecasting/blob/main/src/models/randomforest.py): `src/models/randomforest.py`
- [XGBoost](https://github.com/calvin4370/nhb-museum-visitorship-forecasting/blob/main/src/models/xgboost_model.py): `src/models/xgboost_model.py`
- [Support vector](https://github.com/calvin4370/nhb-museum-visitorship-forecasting/blob/main/src/models/svr.py): `src/models/svr.py`
- [LSTM](https://github.com/calvin4370/nhb-museum-visitorship-forecasting/blob/main/src/models/lstm.py): `src/models/lstm.py`
- [TimeGPT adapter](https://github.com/calvin4370/nhb-museum-visitorship-forecasting/blob/main/src/models/timegpt.py): `src/models/timegpt.py`
- [Fitted model wrapper](https://github.com/calvin4370/nhb-museum-visitorship-forecasting/blob/main/src/models/fitted.py): `src/models/fitted.py`

### Analysis and reporting

- [Optuna persistence](https://github.com/calvin4370/nhb-museum-visitorship-forecasting/blob/main/src/analysis/tuning.py): `src/analysis/tuning.py`
- [Model artifacts](https://github.com/calvin4370/nhb-museum-visitorship-forecasting/blob/main/src/analysis/artifacts.py): `src/analysis/artifacts.py`
- [Permutation importance](https://github.com/calvin4370/nhb-museum-visitorship-forecasting/blob/main/src/analysis/importance.py): `src/analysis/importance.py`
- [Importance report](https://github.com/calvin4370/nhb-museum-visitorship-forecasting/blob/main/src/visualisation/feature_report.py): `src/visualisation/feature_report.py`
- [Forecast plots](https://github.com/calvin4370/nhb-museum-visitorship-forecasting/blob/main/src/visualisation/timeplot.py): `src/visualisation/timeplot.py`
- [Seaborn plots](https://github.com/calvin4370/nhb-museum-visitorship-forecasting/blob/main/src/visualisation/jj_new_plots.py): `src/visualisation/jj_new_plots.py`
- [Museum summaries](https://github.com/calvin4370/nhb-museum-visitorship-forecasting/blob/main/src/visualisation/summary.py): `src/visualisation/summary.py`
- [Deepavali analysis](https://github.com/calvin4370/nhb-museum-visitorship-forecasting/blob/main/src/analysis/deepavali.py): `src/analysis/deepavali.py`
- [Tuning report](https://github.com/calvin4370/nhb-museum-visitorship-forecasting/blob/main/src/analysis/tuning_report.py): `src/analysis/tuning_report.py`
- [Forecast outputs](https://github.com/calvin4370/nhb-museum-visitorship-forecasting/tree/main/outputs): `outputs`

### Runtime orchestration

- [CLI entry](https://github.com/calvin4370/nhb-museum-visitorship-forecasting/blob/main/main.py): `main.py`
- [Argument selection](https://github.com/calvin4370/nhb-museum-visitorship-forecasting/blob/main/src/cli.py): `src/cli.py`
- [Forecast configuration](https://github.com/calvin4370/nhb-museum-visitorship-forecasting/blob/main/config.py): `config.py`
- [Museum pipeline](https://github.com/calvin4370/nhb-museum-visitorship-forecasting/blob/main/src/pipeline.py): `src/pipeline.py`

### Other components

- **Operator**
- **SingStat API**

## Connections

- Operator → CLI entry: runs (evidence: `README.md`)
- CLI entry → Argument selection: parses options (evidence: `main.py`)
- CLI entry → SingStat client: fetches series (evidence: `main.py`)
- CLI entry → Museum pipeline: runs museums (evidence: `main.py`)
- CLI entry → Forecast configuration: selects defaults (evidence: `main.py`)
- SingStat client → SingStat API: requests data (evidence: `src/data/singstat_api.py`)
- SingStat client → Raw series: returns series (evidence: `README.md`)
- Museum pipeline → Feature engineering: engineers features (evidence: `src/pipeline.py`)
- Feature engineering → Event ranges: loads occurrences (evidence: `src/features/data_prep.py`)
- Museum pipeline → Prepared data: saves features (evidence: `README.md`)
- Museum pipeline → Model registry: selects models (evidence: `src/pipeline.py`)
- Model registry → Baseline model: dispatches (evidence: `src/models/model_registry.py`)
- Model registry → Holt-Winters: dispatches (evidence: `src/models/model_registry.py`)
- Model registry → SARIMAX: dispatches (evidence: `src/models/model_registry.py`)
- Model registry → Random Forest: dispatches (evidence: `src/models/model_registry.py`)
- Model registry → XGBoost: dispatches (evidence: `src/models/model_registry.py`)
- Model registry → Support vector: dispatches (evidence: `src/models/model_registry.py`)
- Model registry → LSTM: dispatches (evidence: `src/models/model_registry.py`)
- Model registry → TimeGPT adapter: dispatches (evidence: `src/models/model_registry.py`)
- SARIMAX → Optuna persistence: creates study (evidence: `src/models/sarimax.py`)
- Holt-Winters → Optuna persistence: creates study (evidence: `src/models/holtwinters.py`)
- Museum pipeline → Model artifacts: saves models (evidence: `src/pipeline.py`)
- Museum pipeline → Permutation importance: computes importance (evidence: `src/pipeline.py`)
- Museum pipeline → Importance report: builds report (evidence: `src/pipeline.py`)
- Museum pipeline → Forecast plots: renders plots (evidence: `src/pipeline.py`)
- Museum pipeline → Seaborn plots: renders plots (evidence: `src/pipeline.py`)
- Museum pipeline → Museum summaries: writes summaries (evidence: `src/pipeline.py`)
- Museum pipeline → Deepavali analysis: builds analysis (evidence: `src/pipeline.py`)
- Museum pipeline → Tuning report: writes report (evidence: `src/pipeline.py`)
- Museum pipeline → Forecast outputs: writes forecasts (evidence: `README.md`)
- Fitted model wrapper → Model artifacts: saved by
- Tuning report → Optuna persistence: loads studies (evidence: `src/analysis/tuning_report.py`)
- Museum summaries → Deepavali analysis: includes table (evidence: `src/visualisation/summary.py`)
