FlowSync is a production-grade workflow orchestration platform built on Motia's unified backend runtime. It demonstrates the full power of Motia by combining APIs, background jobs, scheduled tasks, events, streams, states, workflows, and AI agents into a cohesive system with built-in observability.
FlowSync is a Workflow Orchestration Platform that helps you organize and automate complex tasks involving multiple steps. Think of it as a manager that:
- ✅ Keeps track of all workflow steps
- ✅ Ensures steps run in the right order
- ✅ Monitors if something goes wrong
- ✅ Can run multiple workflows simultaneously
- ✅ Shows you what's happening in real-time
Imagine you're running a coffee shop. Making a perfect latte involves several steps:
- Grind coffee beans
- Heat milk
- Brew espresso
- Steam milk
- Combine everything
- Add latte art
FlowSync is like a manager that orchestrates all these steps, ensures they happen in order, monitors progress, and handles multiple orders simultaneously.
POST /workflows- Create new workflowsGET /workflows- List all workflows with filteringPOST /workflows/:id/execute- Execute workflows asynchronouslyGET /executions/:id- Get execution status and resultsGET /workflows/stream- Stream real-time workflow data
- WorkflowAnalyzer: Analyzes workflows and provides optimization recommendations
- WorkflowExecutor: Coordinates workflow execution across multiple steps
- WorkflowOptimizer: Applies optimizations based on analysis results
POST /jobs- Trigger background jobs for async processing- Supports multiple job types: data processing, AI inference, report generation
- Automatic job tracking and state management
- Automated maintenance tasks (runs every 6 hours)
- Cleanup of old executions and job records
- Maintenance logging and reporting
- Workflow creation triggers AI analysis
- Execution events trigger monitoring
- Job completion events update metrics
- All events are logged for observability
- Real-time data streaming endpoint
- Server-Sent Events support
- Live workflow and execution data
GET /metrics- Real-time system metrics- Workflow execution tracking
- Job status monitoring
- Event logging and tracing
- Success rate calculations
- Full observability in Motia Workbench
- Frontend dashboard in
public/directory - Real-time updates
- Complete workflow management UI
FlowSync leverages Motia's unified runtime with the following step types:
create-workflow.step.ts- Create workflowslist-workflows.step.ts- List workflowsexecute-workflow.step.ts- Execute workflowsget-metrics.step.ts- Get system metricsget-execution-status.step.ts- Get execution statustrigger-background-job.step.ts- Trigger background jobsworkflow-stream.step.ts- Stream workflow datahealth-check.step.ts- Health check endpoint
workflow-monitor.step.ts- Monitor all workflow eventsjob-trigger-handler.step.ts- Handle job triggers
workflow-analyzer_step.py- AI-powered workflow analysisworkflow-executor_step.py- AI agent for workflow executionworkflow-optimizer_step.py- AI agent for workflow optimization
background-processor.step.ts- Process async background jobs
scheduled-maintenance.step.ts- Automated maintenance tasks
FlowSync implements an agentic workflow where multiple AI agents work together to analyze, optimize, and execute workflows through Motia's event-driven architecture.
User creates workflow via API
↓
POST /workflows
↓
CreateWorkflow step stores workflow
↓
Emits: workflow-created event
↓
┌─────────────────────────────────────┐
│ WorkflowAnalyzer (AI Agent) │
│ - Analyzes workflow structure │
│ - Generates recommendations │
│ - Emits: workflow-analyzed │
└─────────────────────────────────────┘
↓
┌─────────────────────────────────────┐
│ WorkflowOptimizer (AI Agent) │
│ - Applies optimizations │
│ - Updates workflow │
│ - Emits: workflow-optimized │
└─────────────────────────────────────┘
User executes workflow via API
↓
POST /workflows/:id/execute
↓
ExecuteWorkflow step creates execution
↓
Emits: workflow-execute event
↓
┌─────────────────────────────────────┐
│ WorkflowExecutor (AI Agent) │
│ - Coordinates step execution │
│ - Makes intelligent decisions │
│ - Emits: workflow-execution-completed│
└─────────────────────────────────────┘
- WorkflowAnalyzer - Analyzes workflow complexity, identifies optimization opportunities, generates recommendations
- WorkflowOptimizer - Receives analysis and applies intelligent optimizations to workflows
- WorkflowExecutor - Coordinates workflow execution with AI-powered decision-making
- Node.js (v18+)
- Python (3.8+)
- npm
- Install Dependencies
npm install
pip install -r requirements.txt- Start Development Server
npm run devThis will start:
- Motia runtime
- Workbench UI at
http://localhost:3000
- Start Full-Stack Application (Optional)
./START_FULL_STACK.shThis starts both:
- Backend API at
http://localhost:3000 - Frontend UI at
http://localhost:8080
- Motia Workbench: http://localhost:3000
- Frontend Dashboard: http://localhost:8080 (if using full-stack)
- API Base URL: http://localhost:3000
curl -X POST http://localhost:3000/workflows \
-H "Content-Type: application/json" \
-d '{
"name": "Data Processing Pipeline",
"description": "Processes data through multiple stages",
"steps": [
{
"id": "step-1",
"type": "api",
"config": {"endpoint": "/process"}
},
{
"id": "step-2",
"type": "ai",
"config": {"model": "gpt-4"}
},
{
"id": "step-3",
"type": "job",
"config": {"type": "data_processing"}
}
]
}'What happens:
- Workflow is stored in state
workflow-createdevent is emitted- WorkflowAnalyzer (AI) analyzes the workflow
- WorkflowOptimizer (AI) applies optimizations
- Workflow is ready for execution
curl -X POST http://localhost:3000/workflows/{workflow-id}/execute \
-H "Content-Type: application/json" \
-d '{
"input": {"data": "sample"}
}'What happens:
- Execution record is created
workflow-executeevent is emitted- WorkflowExecutor (AI) coordinates step execution
- Results are stored in state
- Metrics are updated
curl -X POST http://localhost:3000/jobs \
-H "Content-Type: application/json" \
-d '{
"type": "data_processing",
"data": {"records": 1000},
"duration": 5000
}'curl http://localhost:3000/metricscurl http://localhost:3000/workflows/streamWorkflow: Process Order
├─ Step 1: Validate payment
├─ Step 2: Check inventory
├─ Step 3: Reserve items
├─ Step 4: Send confirmation email
└─ Step 5: Update inventory
FlowSync Benefits:
- Ensures all steps complete successfully
- Tracks each order execution
- Handles failures gracefully
- Monitors order processing metrics
Workflow: Publish Article
├─ Step 1: Validate content
├─ Step 2: Generate preview
├─ Step 3: Run spell check
├─ Step 4: Optimize images
├─ Step 5: Publish to website
└─ Step 6: Share on social media
FlowSync Benefits:
- AI agents analyze and optimize the publishing workflow
- Background jobs handle image processing
- Event-driven architecture ensures proper sequencing
- Full observability of the publishing process
Workflow: Weekly Report
├─ Step 1: Collect data from multiple sources
├─ Step 2: Clean and merge data
├─ Step 3: Run analysis (AI agent)
├─ Step 4: Create visualizations
└─ Step 5: Email report to team
FlowSync Benefits:
- AI agents optimize data processing
- Background jobs handle heavy computation
- Scheduled tasks can trigger weekly reports
- Metrics track report generation success
Workflow: Upload Photo
├─ Step 1: Validate file (API)
├─ Step 2: Resize image (Background Job)
├─ Step 3: Generate thumbnails (Background Job)
├─ Step 4: Store in cloud (API)
├─ Step 5: Update database (API)
└─ Step 6: Send notification (Event)
FlowSync Benefits:
- Parallel processing of image operations
- Event-driven notifications
- Full tracking of upload process
- Error handling at each step
- Start the server:
npm run dev- Test health endpoint:
curl http://localhost:3000/health- Test creating a workflow:
curl -X POST http://localhost:3000/workflows \
-H "Content-Type: application/json" \
-d '{
"name": "Test Workflow",
"steps": [{"id": "step1", "type": "api", "config": {}}]
}'- View in Workbench:
- Open http://localhost:3000
- See your workflow
- Test endpoints interactively
- View logs and metrics
GET /health- Health checkGET /metrics- System metricsGET /workflows- List all workflowsPOST /workflows- Create a workflowPOST /workflows/:id/execute- Execute a workflowGET /executions/:id- Get execution statusPOST /jobs- Trigger background jobGET /workflows/stream- Stream workflow data
- Total Steps: 14
- API Steps: 7 (TypeScript)
- AI Agent Steps: 3 (Python)
- Event Steps: 2 (TypeScript)
- Background Job Steps: 1 (TypeScript)
- Scheduled Steps: 1 (TypeScript)
- Stream Steps: 1 (TypeScript)
- Languages: TypeScript + Python (polyglot)
- Creation: User creates workflow via API
- Analysis: AI Analyzer agent analyzes workflow structure
- Optimization: AI Optimizer agent suggests improvements
- Execution: User triggers execution via API
- Processing: AI Executor agent coordinates step execution
- Monitoring: Monitor agent tracks all events
- Completion: Results stored in state, metrics updated
FlowSync uses Motia's built-in state management for:
- Workflows: All workflow definitions
- Executions: Execution history and status
- Background Jobs: Job records and results
- Metrics: System-wide metrics
- Analyses: Workflow analysis results (from AI agents)
- Optimizations: Applied optimizations (from AI agents)
- Event Logs: Observability event logs
- Maintenance Logs: Scheduled maintenance records
- Real-time Metrics: Workflow counts, execution rates, success rates
- Event Logging: All events logged with timestamps
- Execution Tracking: Detailed execution status and results
- Job Monitoring: Background job status and results
- Trace IDs: Built-in tracing for request tracking
- Workbench UI: Visual representation of all workflows and events
- Backend Runtime: Motia (unified runtime)
- Languages: TypeScript (APIs, jobs, events) + Python (AI agents)
- State Management: Motia's built-in state
- Observability: Motia's built-in logging and tracing
- Event System: Motia's event-driven architecture
- Streams: Motia's streaming capabilities
flowsync/
├── steps/
│ ├── create-workflow.step.ts
│ ├── list-workflows.step.ts
│ ├── execute-workflow.step.ts
│ ├── get-metrics.step.ts
│ ├── get-execution-status.step.ts
│ ├── trigger-background-job.step.ts
│ ├── workflow-stream.step.ts
│ ├── workflow-monitor.step.ts
│ ├── job-trigger-handler.step.ts
│ ├── background-processor.step.ts
│ ├── scheduled-maintenance.step.ts
│ ├── health-check.step.ts
│ ├── workflow-analyzer_step.py
│ ├── workflow-executor_step.py
│ └── workflow-optimizer_step.py
├── public/
│ ├── index.html
│ ├── styles.css
│ └── app.js
├── package.json
├── tsconfig.json
├── requirements.txt
├── motia.config.ts
├── START_FULL_STACK.sh
└── README.md
- APIs ✅ - Multiple REST endpoints
- Background Jobs ✅ - Async job processing
- Streams ✅ - Real-time data streaming
- States ✅ - Comprehensive state management
- Workflows ✅ - Workflow orchestration
- Agentic Workflow ✅ - AI agents chained together
- Observability ✅ - Full observability features
- Scheduled Tasks ✅ - Cron-based automation
- Event-Driven ✅ - Event-based coordination
- Polyglot ✅ - TypeScript + Python
npm run build
npm startServer won't start?
# Check if port 3000 is in use
lsof -ti:3000 | xargs kill -9
# Then try again
npm run devEndpoints return errors?
- Check server logs in the terminal
- Make sure server is fully started (wait 20-30 seconds)
- Verify all steps are registered
Can't access Workbench?
- Make sure server is running
- Try http://localhost:3000 in your browser
- Check firewall settings
MIT
Built for the Motia Hackathon 2024
Built with ❤️ using Motia's unified backend runtime