Building applications

A maintainable Boardflare application has a clear boundary between workbook interface, Python application logic, and published results.

Workbook inputs
      │
      ▼
bf.inputs(...)
      │
      ▼
Reactive Python model
      │
      ├── calculations
      ├── validation
      ├── controls
      └── visualizations
      │
      ▼
bf.publish(...)
      │
      ├── BF.OUTPUT(...)
      └── BF.FUNCTION(...)

Keep one upstream input registry

Declare workbook dependencies close together so another author can see what the application depends on.

inputs = bf.inputs(
    transactions=bf.ref("Data!A1:G500", headers=True),
    scenario="Control!B2",
    discount_rate="Control!B3",
)
inputs

Let marimo manage dependency order

Marimo builds a dependency graph from cell references. Put calculations in downstream cells and avoid relying on manual execution order.

Separate model logic from application UI

Keep domain calculations in ordinary Python functions and use marimo UI components for operator controls. This makes the analytical logic easier to test independently of presentation.

Validate at the boundary

Useful checks include required cells and columns, expected data types, bounded assumptions, duplicate identifiers, reconciliations/control totals, and explicit messages for missing data.

Keep one downstream publication registry

bf.publish(
    outputs={"summary": summary, "forecast": forecast},
    functions={"scenario_price": scenario_price},
)

The published registry is live-session state. The workbook persists the source that recreates it, not the Python objects themselves.

Design for two audiences

Authors need dependencies, code, diagnostics, and maintainability. Operators need controls, instructions, outputs, and understandable failure states.

Run mode helps presentation, but it is not an authorization boundary. Do not rely on it to protect secrets or proprietary source from a workbook recipient.

Workbook versus notebook responsibilities

Put in the workbook	Put in the notebook
User-entered assumptions	Analytical model logic
Source data already maintained in Excel	Data transformation that benefits from Python
Reviewable formulas and reconciliations	Statistics, simulation, optimization, specialized libraries
Familiar tables and reports	Reactive controls and custom visualizations
Final worksheet formulas	Published application state and callable functions

Testing before sharing

Test representative inputs, invalid inputs, boundary values, save/reopen behavior, Run-mode startup, BF.OUTPUT() and BF.FUNCTION() cold start, package loading, network failures, and the experience of a second user opening the workbook.