Architecture and Runtime
This page is for developers, security reviewers, and advanced workbook authors who need the implementation model. For normal workbook use, start with Getting Started and Working with Excel.
Boardflare gives substantial Python work a reactive marimo notebook while keeping Excel connected as the workbook-data, assumptions, review, and delivery surface. The shipping runtime uses a stock marimo WebAssembly export rather than a Boardflare fork. Boardflare owns the host integration around that runtime.
Complete runtime topology
The important boundary is that notebook Python does not receive an unrestricted Office.js workbook object. Workbook integration is exposed through the public boardflare package and explicit host capabilities.
Responsibility boundaries
| Layer | Owns |
|---|---|
| Excel / spreadsheet host | Workbook cells, formulas, defined names, Custom XML, host events |
| Excel shared runtime | Long-lived JavaScript runtime used by the task pane and custom functions |
| Spreadsheet Bridge | Host-neutral workbook capability contract and Excel/Univer drivers |
| Boardflare notebook host | Session startup, source persistence, input/output capabilities, worksheet registry integration |
| marimo | Notebook editing, serialization, dependency graph, reactive execution, notebook UI primitives |
| Pyodide | Browser/WebAssembly CPython and compatible package runtime |
boardflare Python package | Public bf.ref, bf.inputs, and bf.publish interfaces plus Anywidget models |
| Notebook worksheet adapters | Streaming BF.OUTPUT and BF.FUNCTION integration with the live publication registry |
| Legacy execution path | BOARDFLARE.EXEC, workbook-stored legacy functions, and the runpy worker |
Boardflare deliberately does not depend on marimo private runtime modules, mutate minified marimo internals, replace the kernel worker, or persist a second executable Python catalog for notebook functions.
Calculation and authentication are separate lifecycles
The Notebook component has calculation semantics even when it is not visible. In Excel, the notebook runtime is kept mounted across task-pane navigation and is allowed to mount while Office authentication is still resolving.
This separation is intentional. A workbook that only needs saved BF.OUTPUT() or BF.FUNCTION() formulas can calculate without waiting for the sign-in UI. Office identity controls Notebook AI eligibility; it is not a prerequisite for the core calculation runtime.
Startup lifecycle
A fresh NotebookSession creates a session ID, secure nonce, source capability, and child iframe. Startup then follows this sequence:
The notebook frontend has a 90-second startup timeout. During normal startup, streaming Excel formulas can remain in Excel's native #BUSY! state until a registry is available or startup fails terminally.
Workbook inputs enter marimo's reactive graph
bf.inputs() declares explicit workbook dependencies:
import boardflare as bf
inputs = bf.inputs(
sales=bf.ref("Sales!A1:D20", headers=True),
scenario="Assumptions!B2",
)
inputs
The returned Anywidget must remain displayed because its model owns the host capability connection.
Before the first workbook snapshot is ready, reading a required input stops the current marimo cell and descendants. This prevents a startup placeholder from becoming a valid published calculation.
A replacement input model becomes authoritative only after its initial snapshot succeeds, so an invalid replacement does not immediately destroy the prior working generation.
Published outputs and functions
bf.publish() is the notebook's explicit worksheet-facing registry:
def discount(price, rate=0.0):
return float(price) * (1 - float(rate))
publication = bf.publish(
outputs={"summary": summary},
functions={"discount": discount},
)
publication
The output model first prepares against the host's workbook date system, converts values in Python, and only then claims the registry.
A successful claim atomically replaces the prior value/function generation. Failed validation or conversion leaves the prior successful generation active.
Live worksheet invocation
BF.OUTPUT() subscribes to a published value. BF.FUNCTION() invokes a retained Python callable through the active publication model.
Replacing the publication generation reinvokes active function subscriptions against the replacement registry. Formula cancellation removes the subscription and sends best-effort cancellation to Python. Asynchronous Python tasks can be canceled; synchronous Python code already blocking the kernel cannot be force-preempted.
Published consumer references
The publication model also receives active worksheet consumer references. The widget can show which formulas use each output or function, and Python can inspect the same mapping through publication.consumers.
In Excel, references follow streaming subscription lifetimes and identify the formula anchor cell. In the standalone Univer host, Boardflare indexes formula cells by scanning and rescanning the used range because that host exposes a different custom-function lifecycle.
Notebook formulas and legacy formulas are separate
The add-in intentionally retains two independent worksheet execution systems:
Notebook functions are not registered in Excel Name Manager and are not persisted as an executable function catalog. The legacy Editor does register Name Manager LAMBDAs that call BOARDFLARE.EXEC. A notebook bundle failure must not prevent the established BOARDFLARE.EXEC association from remaining available.
See Legacy Functions Editor for the compatibility workflow.
Workbook source lifecycle
Boardflare persists notebook source, not a frozen Python interpreter.
An uploaded .py file is staged in memory and starts a new Edit session. It does not overwrite workbook Custom XML until marimo Save reaches Boardflare and persistence verifies successfully. That distinction is why a broken upload can be discarded without deleting the last saved notebook.
Download flushes FileStore writes that marimo has already submitted and exports the latest source acknowledged by Boardflare. It cannot serialize editor changes that marimo has never submitted through Save.
Save and persistence sequence
Marimo's own clean/dirty state is not proof that the asynchronous workbook write completed. The Boardflare save status is authoritative for durable workbook persistence.
Excel Custom XML record
Excel stores one Boardflare notebook Custom XML part. The version-1 record contains notebook source, a SHA-256 digest, the saved Edit/App opening preference (edit/run internally), a timestamp, and the schema version.
Current storage boundaries are:
| Item | Limit |
|---|---|
| Notebook source | 200,000 UTF-8 bytes |
| Complete notebook XML | 1,000,000 bytes |
Live input snapshots, output values, Python function objects, Anywidget generations, worksheet consumer references, and pending function calls are not serialized into the workbook. They are reconstructed by running the saved source.
Spreadsheet Bridge and the standalone demo
Notebook code does not call Office.js directly. Host-specific workbook operations live behind @boardflare/spreadsheet-bridge.
The standalone website demo shares the source/input/output concepts but is not an Excel emulator.
| Capability | Excel | Standalone Univer demo |
|---|---|---|
| Source persistence | Workbook Custom XML | Page-session source |
bf.inputs() | Reactive workbook changes | Reactive workbook changes |
BF.OUTPUT() | Streaming Excel custom function | Univer wrapper |
BF.FUNCTION() | Streaming Excel custom function | One-shot async wrapper |
| Consumer references | Streaming formula anchor addresses | Indexed formula cells |
| Shared-runtime cold start | Excel shared runtime | Browser page lifecycle |
| Notebook AI | Eligible Office work/school identity | Disabled |
Use the browser demo to explore notebooks, but validate save/reopen and worksheet-function startup in the Excel add-in before distributing a workbook.
Public API versus implementation details
Notebook authors should depend on the documented public surface:
bf.ref(...)
bf.inputs(...)
bf.publish(...)
and the worksheet functions:
=BF.OUTPUT("name")
=BF.FUNCTION("name", ...)
Session IDs, nonces, message ports, protocol messages, Custom XML layout, shared-runtime stores, and driver internals are implementation details. Keeping those layers private lets Boardflare change the transport without forcing workbook authors to rewrite notebook code.
For trust boundaries, AI data flow, iframe connection validation, package/network behavior, and executable-workbook guidance, continue to Security and Data Flow.