Architecture

LightFlow is organized around one split: LightFlow owns workflow authorship, while CortexFS owns Linux execution surfaces.

Module Map

src/api.rs

The framework-independent backend service. CLI, future HTTP servers, and Unix socket adapters should call this layer.

src/asset.rs

Self-contained Rust asset discovery and parsing. It uses syn to read META and a deliberately limited workflow builder chain.

src/workflows.rs, src/nodes.rs, src/compositions.rs, src/models.rs

Thin discovery modules for each asset kind.

src/runs.rs

The XDG-backed run store. It writes manifests, original requests, resolved workflows, event streams, trace streams, and output directories.

src/cortex.rs

CortexFS path planning and atomic file submission. It does not call providers directly.

src/main.rs

The CLI adapter around ApiService.

Data Flow

Rust assets
  -> asset discovery
  -> workflow definition
  -> preview or create run
  -> XDG run manifest
  -> CortexFS inbox commit
  -> CortexFS outbox refresh
  -> updated manifest, events, trace

Asset Discovery

LightFlow scans:

lightflow/<kind>/*.rs
src/builtins/<kind>/*.rs

Models are currently project assets only. Nodes, compositions, and workflows may have built-ins.

Run Planning

Creating a run:

1. validates or generates run_id
2. finds the workflow asset
3. parses define()
4. validates referenced models and callables
5. plans CortexFS exchanges for each step
6. writes request, resolved workflow, events, and manifest

Preview uses the same planner without writing state.

API Boundary

The OpenAPI surface is a control plane, not an execution plane. Non-Linux clients can call a Linux-hosted LightFlow server. The server then uses /ctx locally.