Learn about Motia's project structure, file organization, and automatic step discovery system for building scalable workflow applications.

Project Structure

Understanding how to organize your Motia project is crucial for building maintainable and scalable workflow applications. This guide covers the directory structure, file naming conventions, and Motia's automatic step discovery system.

Basic Project Structure

Here's what a typical Motia project looks like:

01-api-gateway.step.ts

02-data-processor.step.py

03-send-notification.step.js

custom-ui.step.tsx

package.json

requirements.txt

tsconfig.json

types.d.ts

motia-workbench.json

config.yml

File Descriptions

File	Purpose	Type	Auto-Generated
`01-api-gateway.step.ts`	TypeScript API endpoint	User Code	❌
`02-data-processor.step.py`	Python data processing	User Code	❌
`03-send-notification.step.js`	JavaScript automation	User Code	❌
`custom-ui.step.tsx`	Optional UI component	User Code	❌
`package.json`	Node.js dependencies (if using JS/TS)	Config	❌
`requirements.txt`	Python dependencies (if using Python)	Config	❌
`tsconfig.json`	TypeScript config (if using TypeScript)	Config	❌
`types.d.ts`	Type definitions for your project	Generated	✅ By TypeScript
`motia-workbench.json`	🤖 Visual workflow positioning	Generated	✅ By Motia
`config.yml`	Optional Motia configuration	Config	❌

The steps/ directory is the heart of your Motia application - this is where all your workflow logic lives. Motia automatically discovers and registers any file following the naming pattern.

Automatic Step Discovery

Key Concept: Automatic Discovery

Motia will automatically discover and register any file that follows the .step. naming pattern as a workflow step. You don't need to manually register steps - just create a file with the right naming pattern and Motia will find it.

Discovery Rules

Motia scans your steps/ directory and automatically registers files as steps based on these rules:

File must contain .step. in the filename (e.g., my-task.step.ts)
File must export a config object defining the step configuration
File must export a handler function containing the step logic
File extension determines the runtime (.ts = TypeScript, .py = Python, .js = JavaScript)

When you run motia dev, Motia will:

Scan the steps/ directory recursively
Find all files matching *.step.*
Parse their config exports to understand step types and connections
Register them in the workflow engine
Make them available in the Workbench

File Naming Convention

Motia uses this specific pattern for automatic step discovery:

[prefix-]descriptive-name.step.[extension]

The .step. part in the filename is required - this is how Motia identifies which files are workflow steps during automatic discovery.

Supported Languages & Extensions

Language	Extension	Example Step File	Runtime
TypeScript	`.ts`	`user-registration.step.ts`	Node.js with TypeScript
Python	`.py`	`data-analysis.step.py`	Python interpreter
JavaScript	`.js`	`send-notification.step.js`	Node.js

Naming Examples by Step Type

Step Type	TypeScript	Python	JavaScript
API Endpoint	`01-auth-api.step.ts`	`01-auth-api.step.py`	`01-auth-api.step.js`
Event Handler	`process-order.step.ts`	`process-order.step.py`	`process-order.step.js`
Cron Job	`daily-report.step.ts`	`daily-report.step.py`	`daily-report.step.js`
Data Processing	`transform-data.step.ts`	`ml-analysis.step.py`	`data-cleanup.step.js`

Step Organization Patterns

Sequential Flow Organization

Perfect for linear workflows where order matters:

01-api-start.step.ts

02-validate-data.step.py

03-process-payment.step.js

04-send-confirmation.step.ts

05-cleanup.step.py

Step	Language	Purpose
`01-api-start.step.ts`	TypeScript	API endpoint
`02-validate-data.step.py`	Python	Data validation
`03-process-payment.step.js`	JavaScript	Payment processing
`04-send-confirmation.step.ts`	TypeScript	Email service
`05-cleanup.step.py`	Python	Cleanup tasks

Language-Specific Configuration

TypeScript/JavaScript Projects

For Node.js-based steps, you'll need:

package.json

{
  "name": "my-motia-app",
  "version": "1.0.0",
  "scripts": {
    "dev": "motia dev",
    "build": "motia build",
    "start": "motia start"
  },
  "dependencies": {
    "motia": "^0.5.12-beta.121",
    "zod": "^3.24.4"
  },
  "devDependencies": {
    "typescript": "^5.7.3",
    "@types/node": "^20.0.0"
  }
}

tsconfig.json (for TypeScript)

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "moduleResolution": "Node",
    "esModuleInterop": true,
    "strict": true,
    "skipLibCheck": true
  },
  "include": ["**/*.ts", "**/*.tsx"],
  "exclude": ["node_modules", "dist"]
}

Python Projects

For Python-based steps:

requirements.txt

# Core Motia dependency
motia>=0.5.12

# Common dependencies
requests>=2.28.0
pydantic>=1.10.0

# Data processing (if needed)
pandas>=1.5.0
numpy>=1.21.0

Step Discovery Examples

Let's see how Motia discovers different step types:

Example 1: TypeScript API Step

steps/user-api.step.ts

import { ApiRouteConfig, Handlers } from 'motia'
import { z } from 'zod'
 
// Motia discovers this file because:
// 1. Filename contains '.step.'
// 2. Exports 'config' object
// 3. Has .ts extension -> uses TypeScript runtime
export const config: ApiRouteConfig = {
  type: 'api',
  name: 'user-api',
  path: '/users',
  method: 'GET',
  emits: ['users.fetched'],
  flows: ['user-management']
}
 
export const handler: Handlers['user-api'] = async (req, { emit }) => {
  await emit({
    topic: 'users.fetched', 
    data: { users: [] }
  })
  
  return {
    status: 200,
    body: { message: 'Users retrieved' }
  }
}

Example 2: Python Event Step

steps/data-processor.step.py

# Motia discovers this file because:
# 1. Filename contains '.step.'  
# 2. Exports 'config' dict
# 3. Has .py extension -> uses Python runtime
 
config = {
    "type": "event",
    "name": "data-processor",
    "description": "Process incoming data with Python",
    "subscribes": ["users.fetched"],
    "emits": ["data.processed"],
    "flows": ["user-management"]
}
 
async def handler(input_data, ctx):
    """Process the data"""
    processed_data = {
        "original": input_data,
        "processed_at": ctx.utils.dates.now().isoformat(),
        "count": len(input_data.get("users", []))
    }
    
    await ctx.emit({
        "topic": "data.processed",
        "data": processed_data
    })

Example 3: JavaScript Automation Step

steps/send-notifications.step.js

// Motia discovers this file because:
// 1. Filename contains '.step.'
// 2. Exports 'config' object  
// 3. Has .js extension -> uses Node.js runtime
 
export const config = {
  type: 'event',
  name: 'send-notifications',
  description: 'Send notifications via multiple channels',
  subscribes: ['data.processed'],
  emits: ['notifications.sent'],
  flows: ['user-management']
}
 
export const handler = async (input, { emit, logger }) => {
  logger.info('Sending notifications', { data: input })
  
  // Send email, SMS, push notifications, etc.
  const results = await Promise.all([
    sendEmail(input),
    sendSMS(input),
    sendPush(input)
  ])
  
  await emit({
    topic: 'notifications.sent',
    data: { 
      results,
      sent_at: new Date().toISOString() 
    }
  })
}
 
async function sendEmail(data) { /* implementation */ }
async function sendSMS(data) { /* implementation */ }  
async function sendPush(data) { /* implementation */ }

Auto-Generated Files

Some files in your Motia project are automatically generated:

types.d.ts - TypeScript generates this for type definitions
motia-workbench.json - Motia manages visual node positions in the Workbench

Multi-Language Project Example

Here's a real-world example showing how the three languages work together:

product-catalog.step.ts

user-auth.step.ts

order-management.step.ts

inventory-sync.step.py

recommendation.step.py

fraud-detection.step.py

email-campaigns.step.js

order-fulfillment.step.js

customer-support.step.js

payment-webhook.step.ts

warehouse-sync.step.py

social-media.step.js

package.json

requirements.txt

tsconfig.json

config.yml

Architecture Breakdown

Layer	Language	Purpose	Examples
API Layer	TypeScript	Fast API responses, type safety	Product catalog, user auth, order management
Processing Layer	Python	Data processing, ML, analytics	Inventory sync, recommendations, fraud detection
Automation Layer	JavaScript	Business automation, workflows	Email campaigns, fulfillment, customer support
Integration Layer	Multi-language	External system connections	Payment webhooks, ERP sync, social media

Language Strengths & When to Use

Language	Best For	Common Step Types	Example Use Cases
TypeScript	API endpoints, type safety, web integrations	API, Event, UI	REST APIs, webhooks, data validation
Python	Data science, ML, automation, integrations	Event, Cron	Data analysis, AI models, file processing
JavaScript	Automation, integrations, general scripting	Event, Cron	Email automation, webhooks, social media

Discovery Troubleshooting

If Motia isn't discovering your steps:

Common Issues

Missing .step. in filename

❌ Won't be discovered:

user-handler.ts

data-processor.py

webhook.js

✅ Will be discovered:

user-handler.step.ts

data-processor.step.py

webhook.step.js

Discovery Verification

Check if your steps are discovered:

# Run Motia in development mode
motia dev
 
# Look for discovery logs:
# ✅ Discovered step: user-api (TypeScript)
# ✅ Discovered step: data-processor (Python)  
# ✅ Discovered step: send-notifications (JavaScript)

Next Steps

Now that you understand how Motia discovers and organizes steps:

Learn about Core Concepts to understand how steps work together
Explore Defining Steps for detailed step creation
Check out API Steps for creating HTTP endpoints
Dive into Event Steps for workflow orchestration

Need help? See our Community Resources for questions, examples, and discussions.

Project Structure

On this page