architecture

Architecture Guide

Overview

This guide covers the architecture and best practices for structuring Motia projects.

Key Takeaway: Motia automatically discovers steps from anywhere in your project. Modern projects use /src for a familiar structure that works seamlessly with Domain-Driven Design.

File Structure

Motia automatically discovers step files from your project. You can organize steps in either:

• /src folder (recommended) - Familiar pattern for most developers
• /steps folder - Traditional Motia pattern
• Both folders simultaneously

Recommended Structure (using /src)

project/
├── src/
│   ├── api/           # API endpoints
│   │   ├── users.step.ts
│   │   └── orders.step.ts
│   ├── events/        # Event handlers
│   │   ├── order-processing.step.ts
│   │   └── notifications.step.ts
│   ├── cron/          # Scheduled tasks
│   │   └── cleanup.step.ts
│   ├── services/      # Business logic
│   ├── repositories/  # Data access
│   └── utils/         # Utilities
└── motia.config.ts

Alternative Structure (using /steps)

project/
├── steps/
│   ├── api/
│   │   └── users.step.ts
│   ├── events/
│   │   └── order-processing.step.ts
│   └── cron/
│       └── cleanup.step.ts
├── src/
│   ├── services/
│   └── utils/
└── motia.config.ts

Create subfolders within your chosen directory to organize related steps into logical groups (domains, features, or flows).

Why /src is recommended:

• Familiar to developers from other frameworks (Next.js, NestJS, etc.)
• Natural co-location with services, repositories, and utilities
• Works seamlessly with Domain-Driven Design patterns
• Cleaner project root with fewer top-level folders

Step Naming Conventions

Typescript

• Use kebab-case for filenames: resource-processing.step.ts
• Include .step before language extension

Python

• Use snake_case for filenames: data_processor_step.py
• Include _step before language extension

Global

• Match handler names to config names
• Use descriptive, action-oriented names