# bradbase/flyingkoala architecture

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

## Overview

FlyingKoala exposes Python calculations to Excel through xlwings, with a central path for loading workbook formulas, caching selected models, and evaluating them against scenario inputs. Domain UDFs provide horticulture degree-day calculations, while separate utilities handle time-series transformations and Bureau of Meteorology observation files. The README also describes formula testing and broader integration UDFs; these are represented as capabilities, but the sampled source does not establish their implementation or wiring. The graph follows sampled calls and data flow; unsampled features are linked only where documentation supports them.

Main entry points: [`flyingkoala/flyingkoala.py`](https://github.com/bradbase/flyingkoala/blob/master/flyingkoala/flyingkoala.py) (Model controls), [`flyingkoala/horticulture/horticulture.py`](https://github.com/bradbase/flyingkoala/blob/master/flyingkoala/horticulture/horticulture.py) (Degree-day UDFs), [`flyingkoala/timeseries/timeseries.py`](https://github.com/bradbase/flyingkoala/blob/master/flyingkoala/timeseries/timeseries.py) (Time-series UDFs), [`examples/unit_test_formulas`](https://github.com/bradbase/flyingkoala/tree/master/examples/unit_test_formulas) (Formula testing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_modeling["Excel model runtime"]
  node_model_api["Model controls<br/>[flyingkoala.py]"]
  node_workbook_loader["Workbook loader<br/>[flyingkoala.py]"]
  node_model_cache[("Model cache<br/>[flyingkoala.py]")]
  node_model_extractor["Model extraction<br/>[flyingkoala.py]"]
  node_scenario_evaluator["Scenario evaluation<br/>[flyingkoala.py]"]
end

subgraph group_udfs["Excel UDFs"]
  node_horticulture_udfs["Degree-day UDFs<br/>[horticulture.py]"]
  node_timeseries_udfs["Time-series UDFs<br/>[timeseries.py]"]
  node_excel_formula_testing["Formula testing"]
  node_integration_udfs["Integration UDFs"]
end

subgraph group_data["Data utilities"]
  node_bom_loader["BOM observation loader<br/>[bom.py]"]
end

subgraph group_dependencies["Calculation dependencies"]
  node_xlwings["xlwings"]
  node_formula_compiler["Formula compiler"]
  node_formula_evaluator["Formula evaluator"]
  node_pandas["Pandas operations"]
end

node_excel_user(("Excel user"))
node_workbook["Excel workbook"]
node_external_file["AXF observation file"]

node_excel_user -->|"edits formulas"| node_workbook
node_excel_user -->|"controls models"| node_model_api
node_workbook -->|"opens workbook"| node_xlwings
node_model_api -->|"accesses workbook"| node_xlwings
node_model_api -->|"reloads formulas"| node_workbook_loader
node_workbook_loader -->|"parses workbook"| node_formula_compiler
node_workbook_loader -->|"reads sheets"| node_workbook
node_model_api -->|"requests model"| node_model_extractor
node_model_extractor -->|"extracts formulas"| node_formula_compiler
node_model_extractor -->|"stores model"| node_model_cache
node_model_api -->|"manages cache"| node_model_cache
node_model_api -->|"evaluates scenarios"| node_scenario_evaluator
node_scenario_evaluator -->|"gets model"| node_model_cache
node_scenario_evaluator -->|"evaluates formula"| node_formula_evaluator
node_horticulture_udfs -->|"loads and evaluates"| node_model_api
node_horticulture_udfs -->|"prepares inputs"| node_pandas
node_timeseries_udfs -->|"transforms series"| node_pandas
node_bom_loader -->|"reads records"| node_external_file
node_excel_user -->|"invokes UDFs"| node_timeseries_udfs
node_excel_user -->|"invokes UDFs"| node_horticulture_udfs
node_excel_formula_testing -.->|"tests formulas"| node_workbook
node_excel_user -.->|"requests integrations"| node_integration_udfs

click node_model_api "https://github.com/bradbase/flyingkoala/blob/master/flyingkoala/flyingkoala.py"
click node_workbook_loader "https://github.com/bradbase/flyingkoala/blob/master/flyingkoala/flyingkoala.py"
click node_model_cache "https://github.com/bradbase/flyingkoala/blob/master/flyingkoala/flyingkoala.py"
click node_model_extractor "https://github.com/bradbase/flyingkoala/blob/master/flyingkoala/flyingkoala.py"
click node_scenario_evaluator "https://github.com/bradbase/flyingkoala/blob/master/flyingkoala/flyingkoala.py"
click node_horticulture_udfs "https://github.com/bradbase/flyingkoala/blob/master/flyingkoala/horticulture/horticulture.py"
click node_timeseries_udfs "https://github.com/bradbase/flyingkoala/blob/master/flyingkoala/timeseries/timeseries.py"
click node_bom_loader "https://github.com/bradbase/flyingkoala/blob/master/flyingkoala/bom/bom.py"
click node_excel_formula_testing "https://github.com/bradbase/flyingkoala/tree/master/examples/unit_test_formulas"
click node_integration_udfs "https://github.com/bradbase/flyingkoala/tree/master/flyingkoala"

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_model_api,node_workbook_loader,node_model_cache,node_model_extractor,node_scenario_evaluator,node_excel_user toneBlue
class node_horticulture_udfs,node_timeseries_udfs,node_excel_formula_testing,node_integration_udfs toneAmber
class node_bom_loader toneMint
class node_xlwings,node_formula_compiler,node_formula_evaluator,node_pandas toneRose
class node_workbook,node_external_file toneIndigo
```

## Components

### Excel model runtime

- [Model controls](https://github.com/bradbase/flyingkoala/blob/master/flyingkoala/flyingkoala.py): `flyingkoala/flyingkoala.py`
- [Workbook loader](https://github.com/bradbase/flyingkoala/blob/master/flyingkoala/flyingkoala.py): `flyingkoala/flyingkoala.py`
- [Model cache](https://github.com/bradbase/flyingkoala/blob/master/flyingkoala/flyingkoala.py): `flyingkoala/flyingkoala.py`
- [Model extraction](https://github.com/bradbase/flyingkoala/blob/master/flyingkoala/flyingkoala.py): `flyingkoala/flyingkoala.py`
- [Scenario evaluation](https://github.com/bradbase/flyingkoala/blob/master/flyingkoala/flyingkoala.py): `flyingkoala/flyingkoala.py`

### Excel UDFs

- [Degree-day UDFs](https://github.com/bradbase/flyingkoala/blob/master/flyingkoala/horticulture/horticulture.py): `flyingkoala/horticulture/horticulture.py`
- [Time-series UDFs](https://github.com/bradbase/flyingkoala/blob/master/flyingkoala/timeseries/timeseries.py): `flyingkoala/timeseries/timeseries.py`
- [Formula testing](https://github.com/bradbase/flyingkoala/tree/master/examples/unit_test_formulas): `examples/unit_test_formulas`
- [Integration UDFs](https://github.com/bradbase/flyingkoala/tree/master/flyingkoala): `flyingkoala`

### Data utilities

- [BOM observation loader](https://github.com/bradbase/flyingkoala/blob/master/flyingkoala/bom/bom.py): `flyingkoala/bom/bom.py`

### Calculation dependencies

- **xlwings**
- **Formula compiler**
- **Formula evaluator**
- **Pandas operations**

### Other components

- **Excel user**
- **Excel workbook**
- **AXF observation file**

## Connections

- Excel user → Excel workbook: edits formulas
- Excel user → Model controls: controls models
- Excel workbook → xlwings: opens workbook
- Model controls → xlwings: accesses workbook
- Model controls → Workbook loader: reloads formulas
- Workbook loader → Formula compiler: parses workbook
- Workbook loader → Excel workbook: reads sheets
- Model controls → Model extraction: requests model
- Model extraction → Formula compiler: extracts formulas
- Model extraction → Model cache: stores model
- Model controls → Model cache: manages cache
- Model controls → Scenario evaluation: evaluates scenarios
- Scenario evaluation → Model cache: gets model
- Scenario evaluation → Formula evaluator: evaluates formula
- Degree-day UDFs → Model controls: loads and evaluates
- Degree-day UDFs → Pandas operations: prepares inputs
- Time-series UDFs → Pandas operations: transforms series
- BOM observation loader → AXF observation file: reads records
- Excel user → Time-series UDFs: invokes UDFs
- Excel user → Degree-day UDFs: invokes UDFs
- Formula testing → Excel workbook: tests formulas
- Excel user → Integration UDFs: requests integrations