NodeGraph

A call to NodeGraph runs one step of a process. That was the part I wanted to make reusable when I built workflows with AI agents in Laravel. A conversation could stop while waiting for someone to reply, then continue later. I needed to know its current state and how it got there.

I had been putting that logic in controllers or spreading it across queue jobs. The transitions became hard to follow. With NodeGraph, I could declare the allowed moves in one PHP class and put the work for each state in its own node.

A state enum maps each state to a node class. The node runs the application's logic and returns a decision about the next state, along with metadata and events. The graph checks that the transition is allowed. An undeclared move throws an exception before the runtime updates the recorded progress.

Progress lives in a thread in the database. Each step also creates a checkpoint with the accumulated metadata and a timestamp. Those records let me inspect the path through a workflow after it finished or stopped. Different workflows can share the same tables because each thread has a graph name and its own state enum.

One step at a time

I kept the scheduling outside the package. The application decides when to call the graph, whether that happens in a request or a queue job. It also decides how to retry failed work. NodeGraph did not need its own background worker to do the job I built it for.

The runtime groups the checkpoint and thread updates in a database transaction. It sends the decision's events after that transaction returns. I wanted listeners to run after the new progress had been written. A state with no outgoing edges ends the process, and another call on a finished thread does no further work.

The package requires PHP 8.4 and supports Laravel 11 and 12. I released it under the MIT license. The last repository push was in April 2026. The source and its usage examples remain public.

What I learned was how much I could leave to the host application. Laravel already had queues and a scheduler. Giving NodeGraph those jobs too would have made it harder to use inside an existing app. The recorded transitions were the part worth extracting.