StateFlowX

Inspiration

StateFlowX actually started from much messier beginnings: multiplayer blackjack experiments, websocket synchronization problems, and what eventually became "blackjack spaghetti hell." As realtime features and runtime state grew more complex, the architecture became increasingly difficult to maintain. Over time, I realized I kept rebuilding the same orchestration, messaging, and state-management patterns across projects, which inspired me to start extracting them into reusable runtime layers.

Part of the inspiration for the transport layer also came from previous work experimenting with Ethereum JSON-RPC systems and protocol-driven communication. I became interested in building a reusable runtime architecture capable of coordinating services, workflows, AI providers, and external systems through consistent execution patterns.

What it does

StateFlowX is a lightweight orchestration runtime for building operational workflows, realtime systems, and AI-driven execution pipelines. It provides transport abstraction, provider management, workflow orchestration, runtime lifecycle management, and event-driven execution tracking.

For this hackathon, StateFlowX was used to orchestrate a workflow involving live weather data, Google ADK agents, Agent Registry integration, MCP tools, MongoDB Atlas, and realtime execution monitoring through a dashboard interface.

How I built it

StateFlowX was built with TypeScript, Node.js, Angular, WebSockets, JSON-RPC, RxJS, and a modular runtime architecture that evolved through multiple refactors over time.

The hackathon implementation integrated Google ADK agents, Agent Registry, MCP tooling, MongoDB Atlas, and Gemini-powered workflows into the runtime. Runtime events are streamed in realtime to a dashboard that visualizes workflow progress, service execution, provider activity, and final artifacts.

The architecture separates transports, services, providers, agents, workflows, execution state, and runtime events into independent layers that can be composed together to build different types of systems.

Challenges I ran into

One of the biggest challenges was integrating MCP tools through Google ADK and Agent Registry while maintaining a clean runtime abstraction. Tool execution, agent orchestration, external service integration, and workflow lifecycle management all introduced additional complexity that traditional AI demos often hide behind a single prompt.

Another challenge was preserving a lightweight architecture while adding support for realtime execution tracking, workflow orchestration, provider management, and external tool integration. Several iterations were required to avoid creating another tightly coupled system.

The MongoDB MCP integration itself became a valuable learning experience, highlighting how difficult it can be to coordinate AI agents, external tools, authentication, runtime state, and execution flow across multiple systems.

Accomplishments that I'm proud of

I successfully evolved the project from experimental realtime game prototypes into a reusable runtime architecture capable of orchestrating services, workflows, AI providers, agents, and external tools.

For this hackathon, StateFlowX was able to coordinate live weather services, Google ADK agents, MCP tools, MongoDB Atlas integration, and realtime execution monitoring through a unified runtime model.

The framework is already usable for practical automation, operational workflows, and AI-driven execution pipelines.

What I learned

I learned that as AI systems become more capable, orchestration becomes increasingly important. The challenge is often not generating a response, but coordinating services, agents, tools, state, execution flow, and observability in a reliable way.

The hackathon reinforced that runtime architecture, workflow management, and tool orchestration are becoming critical components of modern AI systems.

What's next for StateFlowX

Next steps include workflow scheduling, retry and failover strategies, improved observability, richer execution analytics, expanded transport support, additional provider integrations, more MCP tooling examples, and deeper agent orchestration capabilities.

Longer term, I want StateFlowX to become a flexible runtime layer for operational systems, AI workflows, agent-based architectures, and realtime distributed applications.

Built With

• angular.js
• jest
• json-rpc
• nestjs
• node.js
• provider-orchestration
• realtime-execution-pipelines
• rxjs
• typescript
• websockets