Data Layout

LightFlow separates engine source, project assets, runtime state, caches, and heavyweight external files.

Repository Data

src/                     # engine source
src/builtins/            # built-in assets shipped with LightFlow
lightflow/               # versioned project assets
lightflow/models/        # model aliases and resolver hints
lightflow/nodes/         # node assets
lightflow/compositions/  # composition assets
lightflow/workflows/     # workflow assets
openapi/                 # API contract
cortexfs/                # CortexFS submodule
docs-site/               # Bun + Nextra documentation

Engine code and project workflow code are intentionally separate. Agents authoring business pipelines should normally edit lightflow/, not src/.

XDG Runtime Data

Runtime state follows XDG:

$XDG_CONFIG_HOME/lightflow/
$XDG_STATE_HOME/lightflow/
$XDG_CACHE_HOME/lightflow/
$XDG_RUNTIME_DIR/lightflow/

Run Directory

$XDG_STATE_HOME/lightflow/runs/<run_id>/
  manifest.json
  request.json
  resolved_workflow.json
  events.jsonl
  trace.jsonl
  outputs/

resolved_workflow.json preserves the workflow definition used when the run was created, even if the source asset changes later.

Model Weights

Model assets describe aliases and expectations. Heavyweight weights should live in external caches, user-configured model directories, provider-managed stores, or CortexFS model views.

Commit Policy

Commit:

• Rust source
• self-contained asset files
• OpenAPI contracts
• small fixtures
• documentation
• docs-site source and lockfile

Do not commit:

• docs-site/node_modules/
• docs-site/.next/
• docs-site/out/
• real run output
• model weights
• local secrets
• generated caches
• sockets and locks