# diran001/capstone-bbo architecture

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

- Interactive diagram: https://gitdiagram.com/diran001/capstone-bbo
- Repository: https://github.com/diran001/capstone-bbo

## Overview

This is a research workflow for sequential black-box Bayesian optimisation, not a general-purpose optimisation library. Each weekly cycle starts from cumulative observations, fits a function-specific Gaussian Process, selects a candidate using an acquisition rule, and prepares portal submissions; returned scores are registered for the next cycle. The repository also supports historical visualisation and Power BI analysis. The README documents the notebook-led workflow, while the sampled code shows the plotting engine and log-to-dataset export; notebook internals were not sampled, so those connections are documented rather than source-verified.

Main entry points: [`notebooks/bbo_workflow.ipynb`](https://github.com/diran001/capstone-bbo/blob/main/notebooks/bbo_workflow.ipynb) (Weekly notebook), [`data/submissions`](https://github.com/diran001/capstone-bbo/tree/main/data/submissions) (Weekly candidates), [`data/processed`](https://github.com/diran001/capstone-bbo/tree/main/data/processed) (Returned results), [`scripts/bbo_plotting_patch.py`](https://github.com/diran001/capstone-bbo/blob/main/scripts/bbo_plotting_patch.py) (Enhanced plotting)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_optimisation["Optimisation workflow"]
  node_workflow["Weekly notebook<br/>[bbo_workflow.ipynb]"]
  node_tuning["Weekly tuning<br/>[tuning_by_week.csv]"]
  node_gp["GP surrogate<br/>[bbo_workflow.ipynb]"]
  node_acquisition["Acquisition selection<br/>[bbo_workflow.ipynb]"]
end

subgraph group_records["Experiment records"]
  node_observations[("Cumulative observations")]
  node_submission["Weekly candidates"]
  node_processed["Returned results"]
  node_logs[("Execution logs")]
end

subgraph group_visuals["Visualisation"]
  node_plots[("Historical plots")]
  node_plot_engine["Enhanced plotting"]
  node_backfill["Plot backfill"]
end

subgraph group_reporting["Reporting"]
  node_powerbi["Power BI export"]
  node_dataset[("Power BI dataset")]
end

node_researcher(("Researcher"))
node_portal["Course portal"]

node_researcher -->|"runs weekly"| node_workflow
node_workflow -->|"reads observations"| node_observations
node_workflow -->|"fits surrogate"| node_gp
node_workflow -.->|"uses tuning"| node_tuning
node_workflow -->|"selects candidate"| node_acquisition
node_workflow -->|"writes inputs"| node_submission
node_submission -->|"submits query"| node_portal
node_portal -->|"returns scores"| node_processed
node_researcher -->|"places return"| node_processed
node_processed -->|"registers outputs"| node_submission
node_workflow -->|"records execution"| node_logs
node_workflow -->|"generates plots"| node_plot_engine
node_plot_engine -->|"saves figures"| node_plots
node_backfill -->|"calls plotting"| node_plot_engine
node_backfill -->|"reads arrays"| node_observations
node_powerbi -->|"reads logs"| node_logs
node_powerbi -->|"writes dataset"| node_dataset

click node_workflow "https://github.com/diran001/capstone-bbo/blob/main/notebooks/bbo_workflow.ipynb"
click node_observations "https://github.com/diran001/capstone-bbo/tree/main/data/initial_data"
click node_tuning "https://github.com/diran001/capstone-bbo/blob/main/data/config/tuning_by_week.csv"
click node_gp "https://github.com/diran001/capstone-bbo/blob/main/notebooks/bbo_workflow.ipynb"
click node_acquisition "https://github.com/diran001/capstone-bbo/blob/main/notebooks/bbo_workflow.ipynb"
click node_submission "https://github.com/diran001/capstone-bbo/tree/main/data/submissions"
click node_processed "https://github.com/diran001/capstone-bbo/tree/main/data/processed"
click node_logs "https://github.com/diran001/capstone-bbo/tree/main/data/logs"
click node_plots "https://github.com/diran001/capstone-bbo/tree/main/data/plots"
click node_plot_engine "https://github.com/diran001/capstone-bbo/blob/main/scripts/bbo_plotting_patch.py"
click node_backfill "https://github.com/diran001/capstone-bbo/blob/main/scripts/backfill_historical_enhanced_plots.py"
click node_powerbi "https://github.com/diran001/capstone-bbo/blob/main/scripts/build_powerbi_dataset.py"
click node_dataset "https://github.com/diran001/capstone-bbo/tree/main/data/powerbi"

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_workflow,node_tuning,node_gp,node_acquisition toneBlue
class node_observations,node_submission,node_processed,node_logs toneAmber
class node_plots,node_plot_engine,node_backfill toneMint
class node_powerbi,node_dataset toneRose
class node_researcher,node_portal toneIndigo
```

## Components

### Optimisation workflow

- [Weekly notebook](https://github.com/diran001/capstone-bbo/blob/main/notebooks/bbo_workflow.ipynb): `notebooks/bbo_workflow.ipynb`
- [Weekly tuning](https://github.com/diran001/capstone-bbo/blob/main/data/config/tuning_by_week.csv): `data/config/tuning_by_week.csv`
- [GP surrogate](https://github.com/diran001/capstone-bbo/blob/main/notebooks/bbo_workflow.ipynb): `notebooks/bbo_workflow.ipynb`
- [Acquisition selection](https://github.com/diran001/capstone-bbo/blob/main/notebooks/bbo_workflow.ipynb): `notebooks/bbo_workflow.ipynb`

### Experiment records

- [Cumulative observations](https://github.com/diran001/capstone-bbo/tree/main/data/initial_data): `data/initial_data`
- [Weekly candidates](https://github.com/diran001/capstone-bbo/tree/main/data/submissions): `data/submissions`
- [Returned results](https://github.com/diran001/capstone-bbo/tree/main/data/processed): `data/processed`
- [Execution logs](https://github.com/diran001/capstone-bbo/tree/main/data/logs): `data/logs`

### Visualisation

- [Historical plots](https://github.com/diran001/capstone-bbo/tree/main/data/plots): `data/plots`
- [Enhanced plotting](https://github.com/diran001/capstone-bbo/blob/main/scripts/bbo_plotting_patch.py): `scripts/bbo_plotting_patch.py`
- [Plot backfill](https://github.com/diran001/capstone-bbo/blob/main/scripts/backfill_historical_enhanced_plots.py): `scripts/backfill_historical_enhanced_plots.py`

### Reporting

- [Power BI export](https://github.com/diran001/capstone-bbo/blob/main/scripts/build_powerbi_dataset.py): `scripts/build_powerbi_dataset.py`
- [Power BI dataset](https://github.com/diran001/capstone-bbo/tree/main/data/powerbi): `data/powerbi`

### Other components

- **Researcher**
- **Course portal**

## Connections

- Researcher → Weekly notebook: runs weekly (evidence: `README.md`)
- Weekly notebook → Cumulative observations: reads observations (evidence: `README.md`)
- Weekly notebook → GP surrogate: fits surrogate (evidence: `README.md`)
- Weekly notebook → Weekly tuning: uses tuning
- Weekly notebook → Acquisition selection: selects candidate (evidence: `README.md`)
- Weekly notebook → Weekly candidates: writes inputs (evidence: `README.md`)
- Weekly candidates → Course portal: submits query (evidence: `README.md`)
- Course portal → Returned results: returns scores (evidence: `README.md`)
- Researcher → Returned results: places return (evidence: `README.md`)
- Returned results → Weekly candidates: registers outputs (evidence: `README.md`)
- Weekly notebook → Execution logs: records execution (evidence: `README.md`)
- Weekly notebook → Enhanced plotting: generates plots (evidence: `scripts/bbo_plotting_patch.py`)
- Enhanced plotting → Historical plots: saves figures (evidence: `scripts/bbo_plotting_patch.py`)
- Plot backfill → Enhanced plotting: calls plotting (evidence: `scripts/backfill_historical_enhanced_plots.py`)
- Plot backfill → Cumulative observations: reads arrays (evidence: `scripts/backfill_historical_enhanced_plots.py`)
- Power BI export → Execution logs: reads logs (evidence: `scripts/build_powerbi_dataset.py`)
- Power BI export → Power BI dataset: writes dataset (evidence: `scripts/build_powerbi_dataset.py`)
