LightFlow Overview

LightFlow is a backend-first AI workflow system. It treats pipelines as reviewable Rust assets that agents and engineers can edit, instead of making a visual canvas the source of truth.

Reading Path

If you are new to the project, read in this order:

1. Core Concepts for the vocabulary.
2. Architecture for the module boundaries.
3. Asset Model and Workflow DSL for authoring rules.
4. Runs and State and Execution Lifecycle for the runtime path.
5. CortexFS Integration for the execution substrate boundary.
6. Roadmap for the next engineering priorities.

Product Thesis

ComfyUI is excellent at human feedback loops: inspect output, move a slider, change a seed, update a prompt, and judge whether the result improved. LightFlow keeps that human judgment loop, but moves workflow construction into code.

Workflow construction is often software engineering:

• reading provider and model documentation
• resolving models and capabilities
• validating input and output shapes
• building reusable modules
• exposing stable API contracts
• recording runs in an inspectable format

LightFlow lets agents perform that engineering work while humans direct goals, constraints, and review.

Architecture Goals

The first goal is not a full scheduler. The first goal is a small, verifiable backend foundation:

• discover project and built-in Rust assets
• preview workflow runs without writing state
• create XDG-backed run manifests
• submit step requests through CortexFS atomic file semantics
• refresh manifest state from CortexFS outboxes
• expose a framework-independent API service usable by CLI and future HTTP adapters

Repository Zones

• src/ is engine code.
• lightflow/ is versioned project asset code.
• cortexfs/ is the Linux execution substrate submodule.
• openapi/ is the external control-plane contract.
• docs-site/ is this Bun + Nextra documentation site.

Design Principles

• Workflows are code assets, not serialized canvas state.
• Metadata and definition live in one .rs file.
• Project assets stay separate from engine source.
• LightFlow owns workflow authorship and run structure.
• CortexFS owns provider, model, tool, MCP, thread, policy, and audit surfaces.
• Runtime state follows XDG directories and stays out of Git.