Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.coreflux.org/llms.txt

Use this file to discover all available pages before exploring further.

​
Keeping Notebooks Clean and Readable

A well-organized notebook is living documentation. Six months from now, a teammate (or you) should be able to open the file and immediately understand what every cell does and why.
Like a well-kept recipe binder. Each chapter has a clear theme, every recipe has a one-line description above the ingredients, and you can find anything in seconds because nothing’s jumbled together.

​
When to Reach for This

From day one, regardless of project size. Good notebook discipline is cheap to start and expensive to retrofit — by the time your single notebook is hard to navigate, splitting it up means re-reading every cell to figure out where it belongs.

​
Single File or Multiple Files?

There’s no single right answer — it’s a project preference. Both approaches are valid, and both can produce clean, maintainable systems.
ApproachBest forProsTrade-offs
Single fileSmall projects, demos, single-concern systems, getting startedEasy to share and review, everything in one place, simple to deploy as a unitLong files take longer to navigate, harder to deploy parts selectively, awkward for teams editing in parallel
Multiple files in a folderLarger projects, multi-concern systems, team collaborationEasy to find specific concerns, parallel work without conflicts, selective deployment per fileMore files to track, requires a clear naming convention
A small smart-thermostat demo or a single-greenhouse irrigation controller probably belongs in one notebook. A multi-site solar park monitoring platform with industrial routes, normalization, alarms, and storage usually wants the folder layout. When in doubt, start single-file and split when it stops feeling comfortable. The discipline below applies to both approaches.

​
Cell Discipline (Applies Either Way)

A few habits make notebooks self-explanatory regardless of how many files you have:
  • One markdown cell before every LoT cell. State what the next cell does, why it exists, and what topics it reads or publishes. The markdown cell is the contract; the LoT cell is the implementation.
  • One definition per LoT cell. One Action, one Model, or one Route per cell — never bundled. This makes selective re-deployment trivial and keeps execution traces readable.
  • Section headers as standalone markdown cells. Use ## headers to break content into logical sections (## Inverter Models, ## Aggregation Actions, ## Alarm Logic). VS Code’s outline view turns these into a clickable table of contents within the file.
  • An intro markdown cell at the top. What’s in this file, what other notebooks (if any) it depends on, what topics it owns.

​
Single-File Layout

When everything lives in one notebook, lean on section headers to keep it navigable: 
my-thermostat-demo.lotnb
├── # Smart Thermostat Demo (intro markdown cell)
├── ## Models
│   └── (LoT cells: each Model in its own cell, with markdown above)
├── ## Routes
│   └── (LoT cells: each Route in its own cell)
├── ## Processing Actions
│   └── (LoT cells: one Action per cell)
└── ## Alarm Actions
    └── (LoT cells: alarm logic with markdown context)
Read top to bottom: it’s a self-contained tour of your system.

​
Multi-File Layout

For larger projects, one notebook per concern. Numbering reflects the deploy order — define Models before the Actions that publish them, define Routes before the Actions that trigger them. 
my-solar-park/
├── 00_overview.lotnb           // What this project does, who it's for
├── 01_models.lotnb             // All Model definitions
├── 02_routes_ingestion.lotnb   // Industrial routes, REST clients
├── 03_actions_processing.lotnb // Normalization, calculations
├── 04_actions_alarms.lotnb     // Threshold detection, alerts
├── 05_routes_storage.lotnb     // Database and bridge routes
├── 06_rules.lotnb              // Access control
├── AGENTS.md                   // AI assistant conventions
└── README.md                   // How to deploy
Inside each file, the same cell discipline applies: section headers, markdown before each LoT cell, one definition per cell.

​
What This Looks Like in Practice

A snippet from a Models notebook (or the ## Models section of a single-file project):

​
Inverter Models

Standard schemas for every inverter in the fleet. The base model BaseInverter is the contract — every inverter variant inherits from it. Used by the processing actions and stored by the historian route. 
DEFINE MODEL BaseInverter COLLAPSED
    ADD STRING "inverter_id"
    ADD DOUBLE "power_kw"
    ADD DOUBLE "voltage"
    ADD STRING "timestamp"
Hybrid inverter variant — adds battery state for sites with on-site storage. 
DEFINE MODEL HybridInverter FROM BaseInverter
    ADD DOUBLE "battery_soc"
    ADD DOUBLE "battery_power_kw"
Each LoT cell has a markdown cell right above it explaining the why. Six months from now, you’ll thank past-you.

​
Treat Notebooks Like Code

.lotnb files are text — diff them, branch them, review them. Commit your notebooks to git alongside your AGENTS.md and README.md. When a teammate joins, the project’s git repository is everything they need to understand and reproduce the system. Pair the notebooks with an AGENTS.md at the project root so AI assistants generate code that matches your conventions automatically. See AI-Assisted Development Best Practices for the template.

​
Next Steps

LoT Notebooks Usage

Installing and running the VS Code extension.

AI-Assisted Development

Conventions for AGENTS.md and AI-generated LoT.
Last modified on May 20, 2026