> ## 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.
# Project organization
> Keeping LoT notebooks clean, readable, and reviewable — single-file vs multi-file layouts.
## 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.
| Approach | Best for | Pros | Trade-offs |
| ------------------------------ | -------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| **Single file** | Small projects, demos, single-concern systems, getting started | Easy to share and review, everything in one place, simple to deploy as a unit | Long files take longer to navigate, harder to deploy parts selectively, awkward for teams editing in parallel |
| **Multiple files in a folder** | Larger projects, multi-concern systems, team collaboration | Easy to find specific concerns, parallel work without conflicts, selective deployment per file | More 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.
```lot wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
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.
```lot wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
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](/v2.0/ai/best-practices) for the template.
***
## Next Steps
Installing and running the VS Code extension.
Conventions for `AGENTS.md` and AI-generated LoT.