# 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

```bash
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](MIGRATION_STATUS.md) - Progress overview
- [MIGRATION_COMPLETE_ANALYSIS.md](MIGRATION_COMPLETE_ANALYSIS.md) - Complete analysis
- [docs/INDEX.md](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](steps/advoware_proxy/README.md)

2. **Calendar Sync** (4 Steps) - Bidirektionale Synchronisation Advoware ↔ Google
   - Cron-triggered (every 15 min)
   - Manual API trigger
   - Per-employee sync
   - [Details](steps/advoware_cal_sync/README.md)

3. **VMH Integration** (9 Steps) - EspoCRM Webhook-Receiver & Sync
   - Beteiligte sync (bidirectional)
   - Bankverbindungen sync
   - Webhook handlers (create/update/delete)
   - [Details](steps/vmh/README.md)

**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
  ```bash
  # 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:

```bash
# 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](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

```bash
# 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](docs/INDEX.md) - Complete index
- [Migration Status](MIGRATION_STATUS.md) - 100% complete
- [Migration Analysis](MIGRATION_COMPLETE_ANALYSIS.md) - Complete analysis

### Technical Details  
- [Architecture](docs/ARCHITECTURE.md) - System design (Motia III)
- [Advoware Proxy](steps/advoware_proxy/README.md) - API Proxy details
- [Calendar Sync](steps/advoware_cal_sync/README.md) - Sync logic
- [VMH Integration](steps/vmh/README.md) - Webhook handlers

### Migration
- [Migration Guide](../MIGRATION_GUIDE.md) - Old Motia → Motia III patterns

## Testing

```bash
# 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

```bash
# 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