motia-iii/MIGRATION_STATUS.md

# Motia Migration Status

## Overview
Migrating from **old-motia v0.17** (Node.js + Python hybrid) to **Motia III v1.0-RC** (pure Python).

## Old System Analysis

### Location
- Old system: `/opt/motia-iii/old-motia/`
- Old project dir: `/opt/motia-iii/old-motia/bitbylaw/`

### Steps Found in Old System

#### Root Steps (`/opt/motia-iii/old-motia/steps/`)
1. `crm-bbl-vmh-reset-nextcall_step.py`
2. `event_step.py`
3. `hello_step.py`

#### BitByLaw Steps (`/opt/motia-iii/old-motia/bitbylaw/steps/`)

**Advoware Calendar Sync** (`advoware_cal_sync/`):
- `calendar_sync_all_step.py`
- `calendar_sync_api_step.py`
- `calendar_sync_cron_step.py`
- `calendar_sync_event_step.py`
- `audit_calendar_sync.py`
- `calendar_sync_utils.py` (utility module)

**Advoware Proxy** (`advoware_proxy/`):
- `advoware_api_proxy_get_step.py`
- `advoware_api_proxy_post_step.py`
- `advoware_api_proxy_put_step.py`
- `advoware_api_proxy_delete_step.py`

**VMH Integration** (`vmh/`):
- `beteiligte_sync_cron_step.py`
- `beteiligte_sync_event_step.py`
- `bankverbindungen_sync_event_step.py`
- `webhook/bankverbindungen_create_api_step.py`
- `webhook/bankverbindungen_update_api_step.py`
- `webhook/bankverbindungen_delete_api_step.py`
- `webhook/beteiligte_create_api_step.py`
- `webhook/beteiligte_update_api_step.py`
- `webhook/beteiligte_delete_api_step.py`

### Supporting Services/Modules

From `/opt/motia-iii/old-motia/bitbylaw/`:
- `services/advoware.py` - Advoware API wrapper
- `config.py` - Configuration module
- Dependencies: PostgreSQL, Redis, Google Calendar API

## Migration Changes Required

### Key Structural Changes

#### 1. Config Format
```python
# OLD
config = {
    "type": "api",  # or "event", "cron"
    "name": "StepName",
    "path": "/endpoint",
    "method": "GET",
    "cron": "0 5 * * *",
    "subscribes": ["topic"],
    "emits": ["other-topic"]
}

# NEW
from motia import http, queue, cron

config = {
    "name": "StepName",
    "flows": ["flow-name"],
    "triggers": [
        http("GET", "/endpoint")
        # or queue("topic", input=schema)
        # or cron("0 0 5 * * *")  # 6-field!
    ],
    "enqueues": ["other-topic"]
}
```

#### 2. Handler Signature
```python
# OLD - API
async def handler(req, context):
    body = req.get('body', {})
    await context.emit({"topic": "x", "data": {...}})
    return {"status": 200, "body": {...}}

# NEW - API
from motia import ApiRequest, ApiResponse, FlowContext

async def handler(request: ApiRequest, ctx: FlowContext) -> ApiResponse:
    body = request.body
    await ctx.enqueue({"topic": "x", "data": {...}})
    return ApiResponse(status=200, body={...})

# OLD - Event/Queue
async def handler(data, context):
    context.logger.info(data['field'])

# NEW - Queue
async def handler(input_data: dict, ctx: FlowContext):
    ctx.logger.info(input_data['field'])

# OLD - Cron
async def handler(context):
    context.logger.info("Running")

# NEW - Cron
async def handler(input_data: dict, ctx: FlowContext):
    ctx.logger.info("Running")
```

#### 3. Method Changes
- `context.emit()` → `ctx.enqueue()`
- `req.get('body')` → `request.body`
- `req.get('queryParams')` → `request.query_params`
- `req.get('pathParams')` → `request.path_params`
- `req.get('headers')` → `request.headers`
- Return dict → `ApiResponse` object

#### 4. Cron Format
- OLD: 5-field `"0 5 * * *"` (minute hour day month weekday)
- NEW: 6-field `"0 0 5 * * *"` (second minute hour day month weekday)

## Migration Strategy

### Phase 1: Simple Steps (Priority)
Start with simple API proxy steps as they're straightforward:
1. ✅ Example ticketing steps (already in new system)
2. ⏳ Advoware proxy steps (GET, POST, PUT, DELETE)
3. ⏳ Simple webhook handlers

### Phase 2: Complex Integration Steps
Steps with external dependencies:
4. ⏳ VMH sync steps (beteiligte, bankverbindungen)
5. ⏳ Calendar sync steps (most complex - Google Calendar + Redis + PostgreSQL)

### Phase 3: Supporting Infrastructure
- Migrate `services/` modules (advoware.py wrapper)
- Migrate `config.py` to use environment variables properly
- Update dependencies in `pyproject.toml`

### Dependencies to Review
From old `requirements.txt` and code analysis:
- `asyncpg` - PostgreSQL async driver
- `redis` - Redis client
- `google-api-python-client` - Google Calendar API
- `google-auth` - Google OAuth2
- `backoff` - Retry/backoff decorator
- `pytz` - Timezone handling
- `pydantic` - Already in new system
- `requests` / `aiohttp` - HTTP clients for Advoware API

## Status

### Completed
- ✅ Analysis of old system structure
- ✅ MIGRATION_GUIDE.md reviewed
- ✅ Migration patterns documented
- ✅ New system has example ticketing steps
- ✅ **Phase 1: Advoware Proxy Steps migrated** (GET, POST, PUT, DELETE)
- ✅ **Advoware API service module migrated** (services/advoware.py)
- ✅ **Phase 2: VMH Integration - Webhook Steps migrated** (6 endpoints)
- ✅ **EspoCRM API service module migrated** (services/espocrm.py)
- ✅ All endpoints registered and running:
  - **Advoware Proxy:**
    - `GET /advoware/proxy`
    - `POST /advoware/proxy`
    - `PUT /advoware/proxy`
    - `DELETE /advoware/proxy`
  - **VMH Webhooks - Beteiligte:**
    - `POST /vmh/webhook/beteiligte/create`
    - `POST /vmh/webhook/beteiligte/update`
    - `POST /vmh/webhook/beteiligte/delete`
  - **VMH Webhooks - Bankverbindungen:**
    - `POST /vmh/webhook/bankverbindungen/create`
    - `POST /vmh/webhook/bankverbindungen/update`
    - `POST /vmh/webhook/bankverbindungen/delete`

### Current Status: Phase 2 Complete ✅

VMH Webhook endpoints are now receiving EspoCRM webhook events and emitting queue events for processing. The webhook steps handle batch and single entity notifications and provide deduplication via the event handling system.

**Note:** The complex sync handlers (beteiligte_sync_event_step.py, bankverbindungen_sync_event_step.py) are NOT yet migrated as they require additional utility modules:
- `services/beteiligte_sync_utils.py` (663 lines - distributed locking, retry logic, notifications)
- `services/bankverbindungen_mapper.py` (data mapping between EspoCRM and Advoware)
- `services/espocrm_mapper.py` (mapping utilities)
- `services/notification_utils.py` (in-app notifications)

These sync handlers process the queue events emitted by the webhook steps and perform the actual synchronization with Advoware. They will be migrated in Phase 3.

## Notes
- Old system was Node.js + Python hybrid (Python steps as child processes)
- New system is pure Python (standalone SDK)
- No need for Node.js/npm anymore
- iii engine handles all infrastructure (queues, state, HTTP, cron)
- Console replaced Workbench