# motiadev/motia architecture

> Architecture diagram of the GitHub repository motiadev/motia, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/motiadev/motia
- Repository: https://github.com/motiadev/motia

## Overview

##### Project Overview
- Motia is a monorepo hosting a unified backend framework:
- Core runtime (Node + Python + Ruby) for APIs, events, cron jobs, AI agents
- CLI tool (“snap”) for scaffolding, building, deploying flows
- Workbench (React + Vite) for workflow visualization, debugging, monitoring
- Documentation site (Next.js) and example playground

##### High-Level File Structure & Responsibilities
- /packages/core
- Multi-language runners under src/node, src/python, src/ruby
- /packages/snap
- CLI entrypoints: create, install, dev, generate types, build, deploy
- Infrastructure module: API clients, deploy services, error handlers
- /packages/workbench
- Frontend app: React components for flows, logs, state, endpoints, sockets
- /packages/docs
- Next.js site: MDX content, code fetchers, docs API routes
- /packages/test & /playground
- Integration tests, example flow definitions
- CI/CD
- .github/actions & workflows for setup, release, testing
- Other
- compose.yml for local Docker orchestration

##### Core Components
- Developer Tools
- CLI (“snap”) – scaffolding, build & deploy logic, infrastructure API clients
- Runtime Server
- HTTP/API layer (routing for API steps & webhooks)
- Event Bus & Cron Scheduler
- Step Executor (multi-language: Node, Python, Ruby)
- State Manager (adapters for in-memory, Redis, default)
- Trace & Logging subsystem
- External Services
- Redis (optional state persistence / queue)
- External API endpoints (if using Motia Cloud)
- Workbench UI
- WebSocket / HTTP API to runtime
- Visualization (flow graph), logs, state inspector
- Documentation Site (static)

##### Relationships & Data Flows
- Developer → CLI: “snap init/create” → scaffolds project → “snap deploy” calls infrastructure API → Motia Cloud/backend
- Runtime receives HTTP requests (API steps) or internal event triggers → Event Manager routes to Step Executor → update state via State Adapter → emit new events or API responses
- Workbench connects via WebSocket to Runtime → subscribes to trace/log/state streams → real-time UI updates
- CLI’s build output bundles core runtime + user steps → deployed as single package

##### Architectural Patterns & Principles
- Monorepo with clearly separated packages (core, CLI, UI, docs, tests)
- Plugin-like multi-language support—node-runner, python-runner, ruby-runner share RPC and state layers
- Event-driven micro-kernel: central event manager dispatches to handlers
- Adapter pattern for state storage (default/memory/Redis)
- Thin API layer auto-generated from step definitions
- Reactive UI over WebSockets for observability

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Developer Tools
    subgraph "Developer Tools"
        direction TB
        CLI["CLI (snap)"]:::cli
    end

    %% Runtime Core
    subgraph "Runtime Core"
        direction TB
        API["HTTP/API Layer"]:::runtime
        EventMgr["Event Bus & Cron Scheduler"]:::runtime
        Executor["Step Executor<br/>(Node, Python, Ruby)"]:::runtime
        StateMgr["State Manager<br/>(adapters)"]:::adapter
        Logger["Trace & Logging"]:::runtime
    end

    %% Workbench UI
    subgraph "Workbench UI"
        direction TB
        WB["Workbench UI"]:::ui
    end

    %% Documentation
    Docs["Documentation Site"]:::ui

    %% External Services
    Redis["Redis"]:::external
    Cloud["Motia Cloud APIs"]:::external

    %% Connections
    CLI -->|"snap init/create"| CLI
    CLI -->|"deploy API request"| Cloud
    Cloud -->|"HTTP/API call"| API
    API -->|"Event emit"| EventMgr
    EventMgr -->|"Cron trigger"| Executor
    EventMgr -->|"Execute step"| Executor
    Executor -->|"State read/write"| StateMgr
    StateMgr -->|"State persistence"| Redis
    Executor -->|"log/trace"| Logger
    API -->|"WebSocket stream"| WB
    API -->|"HTTP/API call"| WB
    WB -->|"Observability requests"| API

    %% Click Events
    click CLI "https://github.com/motiadev/motia/blob/main/packages/snap/src/cli.ts"
    click API "https://github.com/motiadev/motia/blob/main/packages/core/src/server.ts"
    click EventMgr "https://github.com/motiadev/motia/blob/main/packages/core/src/event-manager.ts"
    click Executor "https://github.com/motiadev/motia/blob/main/packages/core/src/node/node-runner.ts"
    click StateMgr "https://github.com/motiadev/motia/blob/main/packages/core/src/state/adapters/default-state-adapter.ts"
    click Logger "https://github.com/motiadev/motia/blob/main/packages/core/src/LoggerFactory.ts"
    click WB "https://github.com/motiadev/motia/blob/main/packages/workbench/src/main.tsx"
    click Docs "https://github.com/motiadev/motia/tree/main/packages/docs/app/"

    %% Styles
    classDef cli fill:#D0E6FA,stroke:#4A90E2,stroke-width:2px
    classDef runtime fill:#E3FCEF,stroke:#2ECC71,stroke-width:2px
    classDef adapter fill:#FFF3E0,stroke:#FB8C00,stroke-width:2px
    classDef ui fill:#F3E8FF,stroke:#9B59B6,stroke-width:2px
    classDef external fill:#F0F0F0,stroke:#7F8C8D,stroke-width:2px

    %% Legend
    subgraph "Legend"
        direction TB
        A1["Rectangle: Services/Processes"]:::runtime
        A2["Cylinder: Data Stores"]:::external
        A3["Cloud: External APIs"]:::external
        A4["Blue: Developer Tools"]:::cli
        A5["Green: Runtime Core"]:::runtime
        A6["Orange: Adapters/External"]:::adapter
        A7["Purple: UI"]:::ui
    end
```
