ProviderPlane
Workflow-first AI orchestration framework
ProviderPlane
An open-source Node.js framework for applications where AI features have grown beyond isolated model calls and need explicit multi-step orchestration across providers like OpenAI, Anthropic, and Gemini.
Overview
I built ProviderPlane for Node.js applications where AI features have already grown beyond isolated model calls. It gives teams one place to define multi-step workflows across providers without scattering orchestration logic through the rest of the application.
Problem
The hard part is not a single model call. It is what happens once an AI feature becomes a real workflow with branching, retries, fallback, approvals, persistence, or multimodal processing.
Without a workflow layer, that logic gets spread across handlers, services, workers, and helper code, which makes provider choice, sequencing, and failure behavior harder to see and harder to change.
Workflow API
const workflow = pipeline
.chat(generateText.id, "Generate one short inspirational quote in French.", {
normalize: "text"
})
.tts(tts.id, { voice: "alloy", format: "mp3" }, { source: generateText })
.transcribe(transcribe.id, { responseFormat: "text" }, { source: tts, normalize: "text" })
.output((values) => ({
generatedText: String(values.generateText ?? ""),
transcriptText: String(values.transcribe ?? "")
}))
.build();The workflow is declared directly in code, with explicit step dependencies and a typed output shape.
Layered API Design
One of the main design choices was separating workflow authoring from lower-level execution control. I wanted the default API to stay centered on workflow definition, while still leaving room for job-level control and direct client access when a use case genuinely needed it.
That kept the main abstraction focused without boxing the library into one programming model. The workflow layer stays central, while the lower layers exist as escape hatches instead of becoming the center of the design.
The library separates workflow authoring, job-level execution control, and direct provider access into distinct layers.
Workflow Graph
I wanted the workflow layer to handle the kinds of flows that show up quickly in real product work: branching after one step, joining results later, mixing provider-backed operations with approvals or other application-specific logic, and keeping the final output shape intentional.
Representing that as a graph makes the workflow easier to reason about once it stops being linear. Dependencies, branching points, and outputs stay visible instead of being reconstructed from helper code and execution order.
A workflow can branch, rejoin, and mix provider operations with application logic.
Key Design Decisions
- Made the workflow layer the primary API instead of centering the library on raw provider calls.
- Separated workflow authoring, job-level control, and direct client access so lower-level power stayed available without becoming the default path.
- Kept provider fallback, persistence, and resume inside the workflow system rather than pushing those concerns out into application glue.
- Added custom capability steps so application-specific logic could live inside the workflow graph instead of breaking out of it.
- Avoided agent-style planning and other hidden runtime behavior in favor of explicit execution that stays inspectable in code.
OSS Product Work
- Prepared the package for public distribution with npm packaging, CI, changelog, examples, and contribution guidance.
- Built both a documentation site and a project site so the package had a clear public surface beyond the README.
- Wrote getting-started guides, concepts, configuration docs, examples, and API reference to make adoption practical.
- Included runnable examples for workflows, persistence and resume, jobs, and direct client usage so each layer had a clear entry point.
- Treated release quality, docs, and public positioning as part of the product rather than as follow-up work after the code.
Challenges
One challenge was keeping the workflow API explicit without making it tedious to author. The graph needed to stay visible in code, but the common path still had to feel workable for day-to-day application development.
Another challenge was exposing lower-level control without pulling people out of the workflow layer too early. That affected both the API design and the documentation, because the library needed to offer escape hatches without making the escape hatches feel like the real product.
What's Next
The next work is expanding provider coverage, tightening the workflow runtime, and adding more examples around the kinds of multi-step flows teams actually build.
I also want to keep improving the surrounding product surface: clearer docs, better examples, stronger release quality, and more proof that the framework can be adopted incrementally.