bsiggel/motia-iii
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update README and add detailed documentation for Advoware integration and calendar sync

Browse Source
This commit is contained in:
bsiggel
2026-03-01 23:03:01 +00:00
parent 52356e634e
commit 0b8da01b71
4 changed files with 1076 additions and 15 deletions
Download Patch File Download Diff File Expand all files Collapse all files

263
README.md
View File

@@ -1,34 +1,207 @@
# Motia III - BitByLaw Backend
# 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.
Motia Backend-Anwendung powered by the iii engine.
## Project Structure
```
bitbylaw/
├── steps/ # Motia Steps (Business Logic)
├── iii-config.yaml # iii Engine Configuration
├── pyproject.toml # Python Dependencies
└── .venv/ # Python Virtual Environment
```
├── docs/ # Documentation
## Services
## Services & Ports
- **Motia API**: Port 3111 (https://api-motia.bitbylaw.com)
- **iii Console**: Port 3113 (https://motia.bitbylaw.com)
- **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
- `motia.service` - Backend Engine
- `iii-console.service` - Observability Dashboard
## 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
```
@@ -37,10 +210,70 @@ iii -c iii-config.yaml
Services run automatically via systemd on boot.
```bash
# Restart services
systemctl restart motia.service iii-console.service
## 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