motia/bitbylaw

bitbylaw - Motia Integration Platform

Event-driven Integration zwischen Advoware, EspoCRM und Google Calendar über das Motia-Framework.

Quick Start

cd /opt/motia-app/bitbylaw
npm install
pip install -r requirements.txt
npm start

Siehe: docs/DEVELOPMENT.md für Details.

Komponenten

1. Advoware API Proxy - REST-API-Proxy mit HMAC-512 Auth (Details)
2. Calendar Sync - Bidirektionale Synchronisation Advoware ↔ Google (Details)
3. VMH Webhooks - EspoCRM Webhook-Receiver für Beteiligte (Details)
4. Beteiligte Sync ⭐ - Bidirektionale Synchronisation EspoCRM ↔ Advoware (Docs)
   • Event-driven sync mit Redis distributed lock
   • Stammdaten-Sync (Name, Rechtsform, Geburtsdatum, etc.)
   • Template für weitere Advoware-Syncs

Architektur

┌─────────────┐     ┌──────────┐     ┌────────────┐
│  EspoCRM    │────▶│ Webhooks │────▶│  Redis     │
└─────────────┘     └──────────┘     │ Dedup      │
                                     └────────────┘
┌─────────────┐     ┌──────────┐           │
│  Clients    │────▶│  Proxy   │────▶      │
└─────────────┘     └──────────┘           │
                                            ▼
                                     ┌────────────┐
                                     │   Sync     │
                                     │ Handlers   │
                                     └────────────┘
                                            │
                                            ▼
                                     ┌────────────┐
                                     │  Advoware  │
                                     │  Google    │
                                     └────────────┘

Siehe: docs/ARCHITECTURE.md

API Endpoints

Advoware Proxy:

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

Calendar Sync:

• POST /advoware/calendar/sync - Manual trigger

VMH Webhooks:

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

Siehe: docs/API.md

Configuration

Environment Variables via .env oder systemd service:

# Advoware
ADVOWARE_API_BASE_URL=https://www2.advo-net.net:90/
ADVOWARE_API_KEY=your_base64_key
ADVOWARE_USER=api_user
ADVOWARE_PASSWORD=your_password

# Redis
REDIS_HOST=localhost
REDIS_PORT=6379

# Google Calendar
GOOGLE_CALENDAR_SERVICE_ACCOUNT_PATH=/opt/motia-app/service-account.json

Siehe:

• docs/CONFIGURATION.md
• docs/GOOGLE_SETUP.md - Service Account Setup

Deployment

Production deployment via systemd:

sudo systemctl status motia.service
sudo journalctl -u motia.service -f

Siehe: docs/DEPLOYMENT.md

Documentation

Getting Started

• Development Guide - Setup, Coding Standards, Testing
• Configuration - Environment Variables
• Deployment - Production Setup

Technical Details

• Architecture - System Design, Datenflüsse
• API Reference - HTTP Endpoints, Event Topics
• Troubleshooting - Common Issues

Components

• Advoware Proxy - API Proxy Details
• Calendar Sync - Sync Logic
• VMH Webhooks - Webhook Handlers
• Advoware Service - API Client

Step Documentation

Jeder Step hat eine detaillierte .md Dokumentation neben der .py Datei.

Project Structure

bitbylaw/
├── docs/                    # Documentation
├── steps/                   # Motia Steps  
│   ├── advoware_proxy/     # API Proxy Steps + Docs
│   ├── advoware_cal_sync/  # Calendar Sync Steps + Docs
│   └── vmh/                # Webhook Steps + Docs
├── services/               # Shared Services
│   └── advoware.py        # API Client + Doc
├── config.py              # Configuration Loader
├── package.json           # Node.js Dependencies
└── requirements.txt       # Python Dependencies

Technology Stack

• Framework: Motia v0.8.2-beta.139 (Event-Driven Backend)
• Languages: Python 3.13, Node.js 18, TypeScript
• Data Store: Redis (Caching, Locking, Deduplication)
• External APIs: Advoware REST API, Google Calendar API, EspoCRM

Development

# Development mode
npm run dev

# Generate types
npm run generate-types

# Clean build
npm run clean && npm install

---

Projektstruktur

bitbylaw/
├── docs/                    # Comprehensive documentation
│   ├── advoware/           # Advoware API documentation (Swagger)
│   └── *.md                # Architecture, Development, Configuration, etc.
├── scripts/                # Utility scripts for maintenance
│   └── calendar_sync/      # Calendar sync helper scripts
├── services/               # Shared service implementations
├── steps/                  # Motia step implementations
│   ├── advoware_proxy/     # REST API proxy steps
│   ├── advoware_cal_sync/  # Calendar synchronization steps
│   └── vmh/                # EspoCRM webhook handlers
├── src/                    # TypeScript sources (unused currently)
└── config.py               # Central configuration

Key Files:

• docs/INDEX.md - Documentation navigation
• docs/ARCHITECTURE.md - System architecture
• docs/advoware/advoware_api_swagger.json - Advoware API spec
• scripts/calendar_sync/README.md - Utility scripts

---

Testing

# Test Advoware Proxy
curl -X GET "http://localhost:3000/advoware/proxy?endpoint=employees"

# Test Calendar Sync
curl -X POST "http://localhost:3000/advoware/calendar/sync" \
  -H "Content-Type: application/json" \
  -d '{"full_content": true}'

# Test Webhook
curl -X POST "http://localhost:3000/vmh/webhook/beteiligte/create" \
  -H "Content-Type: application/json" \
  -d '[{"id": "test-123"}]'

License

[Your License]

Support

• Issues: [GitHub Issues]
• Docs: docs/
• Logs: sudo journalctl -u motia.service -f