bitbylaw - Motia III Integration Platform

✅ Migration Complete: 21/21 Steps (100%)

Event-driven Integration zwischen Advoware, EspoCRM und Google Calendar mit Motia III v1.0-RC (Pure Python).

Quick Start

cd /opt/motia-iii/bitbylaw

# Start iii Engine
/opt/bin/iii -c iii-config.yaml

# Start iii Console (Web UI) - separate terminal
/opt/bin/iii-console --enable-flow --host 0.0.0.0 --port 3113 \
  --engine-host localhost --engine-port 3111 --ws-port 3114

Open browser: http://localhost:3113/

Migration Status

This project has been fully migrated from old Motia v0.17 (Node.js + Python) to Motia III v1.0-RC (Pure Python).

See:

• MIGRATION_STATUS.md - Progress overview
• MIGRATION_COMPLETE_ANALYSIS.md - Complete analysis
• docs/INDEX.md - Complete documentation index

Komponenten

1. Advoware API Proxy (4 Steps) - REST-API-Proxy mit HMAC-512 Auth

   • GET, POST, PUT, DELETE proxies
   • Details

2. Calendar Sync (4 Steps) - Bidirektionale Synchronisation Advoware ↔ Google

   • Cron-triggered (every 15 min)
   • Manual API trigger
   • Per-employee sync
   • Details

3. VMH Integration (9 Steps) - EspoCRM Webhook-Receiver & Sync

   • Beteiligte sync (bidirectional)
   • Bankverbindungen sync
   • Webhook handlers (create/update/delete)
   • Details

Total: 17 Steps registered

Architektur

┌─────────────┐     ┌──────────┐     ┌────────────┐
│  EspoCRM    │────▶│ Webhooks │────▶│  Redis     │
│   (VMH)     │     │ (HTTP)   │     │ Locking    │
└─────────────┘     └──────────┘     └────────────┘
                                            │
┌─────────────┐     ┌──────────┐           │
│  Clients    │────▶│  Proxy   │────▶      │
│             │     │ API  API │           │
└─────────────┘     └──────────┘           ▼
                                     ┌────────────┐
    Cron (15min)                     │   Motia    │
         │                           │   Steps    │
         └──────────────────────────▶│  (Python)  │
                                     └────────────┘
                                            │
                                            ▼
                                     ┌────────────┐
                                     │  Advoware  │
                                     │  Google    │
                                     │  Calendar  │
                                     └────────────┘

API Endpoints

Advoware Proxy:

• GET/POST/PUT/DELETE /advoware/proxy?endpoint=...

Calendar Sync:

• POST /advoware/calendar/sync - Manual trigger

  # Sync single employee
  curl -X POST "http://localhost:3111/advoware/calendar/sync" \
    -H "Content-Type: application/json" \
    -d '{"kuerzel": "PB"}'
  
  # Sync all employees
  curl -X POST "http://localhost:3111/advoware/calendar/sync" \
    -H "Content-Type: application/json" \
    -d '{"kuerzel": "ALL"}'
  

VMH Webhooks:

• POST /vmh/webhook/beteiligte/create
• POST /vmh/webhook/beteiligte/update
• POST /vmh/webhook/beteiligte/delete
• POST /vmh/webhook/bankverbindungen/create
• POST /vmh/webhook/bankverbindungen/update
• POST /vmh/webhook/bankverbindungen/delete

Configuration

Environment variables loaded from systemd service or .env file:

# Advoware API
ADVOWARE_API_BASE_URL=https://www2.advo-net.net:90/
ADVOWARE_PRODUCT_ID=64
ADVOWARE_APP_ID=your_app_id
ADVOWARE_API_KEY=your_base64_hmac_key
ADVOWARE_KANZLEI=your_kanzlei
ADVOWARE_DATABASE=your_database
ADVOWARE_USER=api_user
ADVOWARE_ROLE=2
ADVOWARE_PASSWORD=your_password
ADVOWARE_TOKEN_LIFETIME_MINUTES=55
ADVOWARE_API_TIMEOUT_SECONDS=30

# Redis
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_DB_CALENDAR_SYNC=1
REDIS_TIMEOUT_SECONDS=5

# Google Calendar
GOOGLE_CALENDAR_SERVICE_ACCOUNT_PATH=/path/to/service-account.json

# PostgreSQL
POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_USER=bitbylaw
POSTGRES_PASSWORD=your_password
POSTGRES_DATABASE=bitbylaw

See docs/INDEX.md for complete configuration guide.

Project Structure

bitbylaw/
├── docs/                        # Documentation

## Services & Ports

- **iii Engine (API)**: Port 3111 (https://api-motia.bitbylaw.com)
- **iii Console (Web UI)**: Port 3113 (https://motia.bitbylaw.com)
- **Streams/WebSocket**: Port 3114
- **Redis**: Port 6379 (localhost)
- **PostgreSQL**: Port 5432 (localhost)eps)
│   ├── advoware_cal_sync/      # Calendar Sync (4 steps)
│   └── vmh/                    # VMH Integration (9 steps)
├── services/                    # Shared Services
│   ├── advoware_service.py     # Advoware API Client
│   ├── espocrm.py              # EspoCRM API Client
│   └── ...                     # Other services
├── iii-config.yaml             # iii Engine Configuration
├── pyproject.toml              # Python Dependencies (uv)
├── MIGRATION_STATUS.md         # Migration progress
├── MIGRATION_COMPLETE_ANALYSIS.md  # Migration analysis
└── .venv/                      # Python Virtual Environment

Systemd Services

Systemd Services

• motia.service - iii Engine (Backend)
• iii-console.service - iii Console (Observability Dashboard)

Service Management

# Status
systemctl status motia.service
systemctl status iii-console.service

# Restart

## Development

```bash
# Install dependencies
cd /opt/motia-iii/bitbylaw
uv sync

# Start iii Engine (development)
iii -c iii-config.yaml

# Start iii Console (separate terminal)
iii-console --enable-flow --host 0.0.0.0 --port 3113 \
  --engine-host localhost --engine-port 3111 --ws-port 3114

# Test step import
uv run python -c "from steps.advoware_proxy import advoware_api_proxy_get_step"

# Check registered steps
curl http://localhost:3111/_console/functions

# Start locally
iii -c iii-config.yaml

Production

Services run automatically via systemd on boot.

Technology Stack

• Framework: Motia III v1.0-RC (Pure Python, iii Engine)
• Language: Python 3.13
• Package Manager: uv
• Data Store: Redis (Caching, Locking), PostgreSQL (Sync State)
• External APIs:
  • Advoware REST API (HMAC-512 auth)
  • Google Calendar API (Service Account)
  • EspoCRM API (X-Api-Key auth)

Documentation

Getting Started

• Documentation Index - Complete index
• Migration Status - 100% complete
• Migration Analysis - Complete analysis

Technical Details

• Architecture - System design (Motia III)
• Advoware Proxy - API Proxy details
• Calendar Sync - Sync logic
• VMH Integration - Webhook handlers

Migration

• Migration Guide - Old Motia → Motia III patterns

Testing

# Test HTTP endpoints
curl http://localhost:3111/advoware/proxy?endpoint=employees

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

# Check registered functions
curl http://localhost:3111/_console/functions | grep "Calendar"

# View logs in Console
open http://localhost:3113/

Production

Services run automatically via systemd on boot.

Deployed on: motia.bitbylaw.com
Deployment Date: März 2026

# Restart production services
sudo systemctl restart motia.service iii-console.service

# View production logs
journalctl -u motia.service -f
journalctl -u iii-console.service -f

# Check service status
systemctl status motia.service iii-console.service

View logs

journalctl -u motia.service -f journalctl -u iii-console.service -f

## Deployment

Deployed on: motia.bitbylaw.com  
Date: März 2026