bsiggel/motia-iii

Fork 0

Files

bsiggel 0b8da01b71 Update README and add detailed documentation for Advoware integration and calendar sync

2026-03-01 23:03:01 +00:00

7.5 KiB

Raw Blame History

Documentation Index - Motia III

Getting Started

New to the project? Start here:

README.md - Project Overview & Quick Start
MIGRATION_STATUS.md - Migration Progress (100% Complete!)
MIGRATION_COMPLETE_ANALYSIS.md - Complete Migration Analysis

Migration to Motia III

Status: ✅ 100% Complete (21/21 Steps migrated)

MIGRATION_GUIDE.md - Complete migration patterns
- Old Motia v0.17 → Motia III v1.0-RC
- TypeScript + Python Hybrid → Pure Python
- Configuration changes, trigger patterns, API differences
MIGRATION_STATUS.md - Current migration status
MIGRATION_COMPLETE_ANALYSIS.md - Complete analysis

Core Documentation

For Developers

ARCHITECTURE.md - System design and architecture
- Components, Data Flow, Event-Driven Design
- Updated for Motia III patterns

For Operations

DEPLOYMENT.md - Production deployment (if available)
- Installation, systemd, nginx, Monitoring
CONFIGURATION.md - Environment configuration (if available)
- All environment variables, secrets management

Component Documentation

Steps (Business Logic)

Advoware Proxy (Module README): Universal HTTP proxy for Advoware API with automatic authentication.

GET, POST, PUT, DELETE proxies
HMAC-512 authentication
Redis token caching

Calendar Sync (Module README): Bidirectional sync between Advoware appointments and Google Calendar.

calendar_sync_cron_step.py - Auto trigger (every 15 min)
calendar_sync_api_step.py - Manual trigger endpoint
calendar_sync_all_step.py - Employee cascade handler
calendar_sync_event_step.py - Per-employee sync logic (1053 lines)

VMH Integration (Module README): Webhooks and bidirectional sync between EspoCRM and Advoware.

Beteiligte Sync (Bidirectional EspoCRM ↔ Advoware)
- Cron job (every 15 min)
- Event handlers for create/update/delete
Webhooks (6 endpoints)
- Beteiligte: create, update, delete
- Bankverbindungen: create, update, delete

Services

Service modules providing API clients and business logic:

advoware_service.py - Advoware API client (HMAC-512 auth, token caching)
espocrm.py - EspoCRM API client
advoware.py - Legacy Advoware service (deprecated)
Sync utilities and mappers

Motia III Patterns

Step Configuration

Old (Motia v0.17):

config = {
    'type': 'api',  # or 'event', 'cron'
    'name': 'MyStep',
    'method': 'POST',
    'path': '/my-step',
    'emits': ['my-event'],
    'subscribes': ['other-event']
}

New (Motia III):

from motia import http, queue, cron

config = {
    'name': 'MyStep',
    'flows': ['my-flow'],
    'triggers': [
        http('POST', '/my-step')  # or queue('topic') or cron('0 */15 * * * *')
    ],
    'enqueues': ['my-event']
}

Handler Signatures

HTTP Trigger:

from motia import ApiRequest, ApiResponse, FlowContext

async def handler(request: ApiRequest, ctx: FlowContext) -> ApiResponse:
    # Access: request.body, request.query_params, request.path_params
    # Enqueue: await ctx.enqueue(topic='...', data={...})
    # Log: ctx.logger.info('...')
    return ApiResponse(status=200, body={...})

Queue Trigger:

async def handler(input_data: dict, ctx: FlowContext) -> None:
    # Process queue data
    await ctx.enqueue(topic='next-step', data={...})

Cron Trigger:

async def handler(input_data: None, ctx: FlowContext) -> None:
    # Cron jobs receive no input
    ctx.logger.info('Cron triggered')

Key Differences from Old Motia

Old Motia v0.17	Motia III v1.0-RC
`type: 'api'`	`triggers: [http()]`
`type: 'event'`	`triggers: [queue()]`
`type: 'cron'`	`triggers: [cron()]`
`context.emit()`	`ctx.enqueue()`
`emits: [...]`	`enqueues: [...]`
`subscribes: [...]`	Moved to trigger: `queue('topic')`
5-field cron	6-field cron (prepend seconds)
`context.logger`	`ctx.logger`
Motia Workbench	iii Console
Node.js + Python	Pure Python

Documentation Structure

docs/
├── INDEX.md                  # This file
├── ARCHITECTURE.md           # System design (Motia III)
└── advoware/
    └── (optional API specs)

steps/{module}/
├── README.md                 # Module overview
└── {step_name}_step.py       # Step implementation

services/
└── {service_name}.py         # Service implementations

MIGRATION_GUIDE.md            # Complete migration guide
MIGRATION_STATUS.md           # Migration progress
MIGRATION_COMPLETE_ANALYSIS.md # Final analysis

Quick Reference

Common Tasks

Task	Documentation
Understand migration	MIGRATION_GUIDE.md
Check migration status	MIGRATION_STATUS.md
Understand architecture	ARCHITECTURE.md
Calendar sync overview	steps/advoware_cal_sync/README.md
Proxy API usage	steps/advoware_proxy/README.md
VMH sync details	steps/vmh/README.md

Code Locations

Component	Location	Documentation
API Proxy Steps	`steps/advoware_proxy/`	README
Calendar Sync Steps	`steps/advoware_cal_sync/`	README
VMH Steps	`steps/vmh/`	README
Advoware Service	`services/advoware_service.py`	(in-code docs)
Configuration	`iii-config.yaml`	System config
Environment	`.env` or systemd	Environment variables

Running the System

Start iii Engine

cd /opt/motia-iii/bitbylaw
/opt/bin/iii -c iii-config.yaml

Start iii Console (Web UI)

/opt/bin/iii-console --enable-flow --host 0.0.0.0 --port 3113 \
  --engine-host 192.168.67.233 --engine-port 3111 --ws-port 3114

Access Web Console

Open browser: http://localhost:3113/

Check Registered Steps

curl http://localhost:3111/_console/functions | python3 -m json.tool

Testing

Test HTTP Step

# Calendar sync API
curl -X POST "http://localhost:3111/advoware/calendar/sync" \
  -H "Content-Type: application/json" \
  -d '{"kuerzel": "PB"}'

# Advoware proxy
curl "http://localhost:3111/advoware/proxy?endpoint=employees"

Trigger Cron Manually

curl -X POST "http://localhost:3111/_console/cron/trigger" \
  -H "Content-Type: application/json" \
  -d '{"function_id": "steps::Calendar Sync Cron Job::trigger::0"}'

Check Logs

View logs in iii Console or via API:

curl "http://localhost:3111/_console/logs"

External Resources

Support

Migration Questions: Check MIGRATION_GUIDE.md
Runtime Issues: Check iii Console logs
Step Not Showing: Verify import errors in logs
Redis Issues: Check Redis connection in services/

7.5 KiB Raw Blame History