Files

bitbylaw ae1d96f767 Add sync strategy documentation and templates for bidirectional sync between EspoCRM and Advoware

- Introduced SYNC_STRATEGY_ARCHIVE.md detailing the sync process, status values, and flow for updating entities from EspoCRM to Advoware and vice versa.
- Created SYNC_TEMPLATE.md as a guide for implementing new syncs, including field definitions, mapper examples, sync utilities, event handlers, and cron jobs.
- Added README_SYNC.md for the Beteiligte sync event handler, outlining its functionality, event subscriptions, optimizations, error handling, and performance metrics.

2026-02-07 15:54:13 +00:00

6.8 KiB

Raw Blame History

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

Advoware API Proxy - REST-API-Proxy mit HMAC-512 Auth (Details)
Calendar Sync - Bidirektionale Synchronisation Advoware ↔ Google (Details)
VMH Webhooks - EspoCRM Webhook-Receiver für Beteiligte (Details)
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

6.8 KiB Raw Blame History