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

2026-03-01 23:03:01 +00:00
parent 52356e634e
commit 0b8da01b71
4 changed files with 1076 additions and 15 deletions
--- a/docs/INDEX.md
+++ b/docs/INDEX.md
@@ -0,0 +1,246 @@
+# Documentation Index - Motia III
+
+## Getting Started
+
+**New to the project?** Start here:
+
+1. [README.md](../README.md) - Project Overview & Quick Start
+2. [MIGRATION_STATUS.md](../MIGRATION_STATUS.md) - Migration Progress (100% Complete!)
+3. [MIGRATION_COMPLETE_ANALYSIS.md](../MIGRATION_COMPLETE_ANALYSIS.md) - Complete Migration Analysis
+
+## Migration to Motia III
+
+**Status: ✅ 100% Complete (21/21 Steps migrated)**
+
+- **[MIGRATION_GUIDE.md](../MIGRATION_GUIDE.md)** - Complete migration patterns
+  - Old Motia v0.17 → Motia III v1.0-RC
+  - TypeScript + Python Hybrid → Pure Python
+  - Configuration changes, trigger patterns, API differences
+- **[MIGRATION_STATUS.md](../MIGRATION_STATUS.md)** - Current migration status
+- **[MIGRATION_COMPLETE_ANALYSIS.md](../MIGRATION_COMPLETE_ANALYSIS.md)** - Complete analysis
+
+## Core Documentation
+
+### For Developers
+- **[ARCHITECTURE.md](ARCHITECTURE.md)** - System design and architecture
+  - Components, Data Flow, Event-Driven Design
+  - Updated for Motia III patterns
+
+### For Operations
+- **[DEPLOYMENT.md](DEPLOYMENT.md)** - Production deployment (if available)
+  - Installation, systemd, nginx, Monitoring
+- **[CONFIGURATION.md](CONFIGURATION.md)** - Environment configuration (if available)
+  - All environment variables, secrets management
+
+## Component Documentation
+
+### Steps (Business Logic)
+
+**Advoware Proxy** ([Module README](../steps/advoware_proxy/README.md)):
+Universal HTTP proxy for Advoware API with automatic authentication.
+- GET, POST, PUT, DELETE proxies
+- HMAC-512 authentication
+- Redis token caching
+
+**Calendar Sync** ([Module README](../steps/advoware_cal_sync/README.md)):
+Bidirectional sync between Advoware appointments and Google Calendar.
+- `calendar_sync_cron_step.py` - Auto trigger (every 15 min)
+- `calendar_sync_api_step.py` - Manual trigger endpoint
+- `calendar_sync_all_step.py` - Employee cascade handler
+- `calendar_sync_event_step.py` - Per-employee sync logic (1053 lines)
+
+**VMH Integration** ([Module README](../steps/vmh/README.md)):
+Webhooks and bidirectional sync between EspoCRM and Advoware.
+- **Beteiligte Sync** (Bidirectional EspoCRM ↔ Advoware)
+  - Cron job (every 15 min)
+  - Event handlers for create/update/delete
+- **Webhooks** (6 endpoints)
+  - Beteiligte: create, update, delete
+  - Bankverbindungen: create, update, delete
+
+### Services
+
+Service modules providing API clients and business logic:
+- `advoware_service.py` - Advoware API client (HMAC-512 auth, token caching)
+- `espocrm.py` - EspoCRM API client
+- `advoware.py` - Legacy Advoware service (deprecated)
+- Sync utilities and mappers
+
+## Motia III Patterns
+
+### Step Configuration
+
+**Old (Motia v0.17):**
+```python
+config = {
+    'type': 'api',  # or 'event', 'cron'
+    'name': 'MyStep',
+    'method': 'POST',
+    'path': '/my-step',
+    'emits': ['my-event'],
+    'subscribes': ['other-event']
+}
+```
+
+**New (Motia III):**
+```python
+from motia import http, queue, cron
+
+config = {
+    'name': 'MyStep',
+    'flows': ['my-flow'],
+    'triggers': [
+        http('POST', '/my-step')  # or queue('topic') or cron('0 */15 * * * *')
+    ],
+    'enqueues': ['my-event']
+}
+```
+
+### Handler Signatures
+
+**HTTP Trigger:**
+```python
+from motia import ApiRequest, ApiResponse, FlowContext
+
+async def handler(request: ApiRequest, ctx: FlowContext) -> ApiResponse:
+    # Access: request.body, request.query_params, request.path_params
+    # Enqueue: await ctx.enqueue(topic='...', data={...})
+    # Log: ctx.logger.info('...')
+    return ApiResponse(status=200, body={...})
+```
+
+**Queue Trigger:**
+```python
+async def handler(input_data: dict, ctx: FlowContext) -> None:
+    # Process queue data
+    await ctx.enqueue(topic='next-step', data={...})
+```
+
+**Cron Trigger:**
+```python
+async def handler(input_data: None, ctx: FlowContext) -> None:
+    # Cron jobs receive no input
+    ctx.logger.info('Cron triggered')
+```
+
+### Key Differences from Old Motia
+
+| Old Motia v0.17 | Motia III v1.0-RC |
+|-----------------|-------------------|
+| `type: 'api'` | `triggers: [http()]` |
+| `type: 'event'` | `triggers: [queue()]` |
+| `type: 'cron'` | `triggers: [cron()]` |
+| `context.emit()` | `ctx.enqueue()` |
+| `emits: [...]` | `enqueues: [...]` |
+| `subscribes: [...]` | Moved to trigger: `queue('topic')` |
+| 5-field cron | 6-field cron (prepend seconds) |
+| `context.logger` | `ctx.logger` |
+| Motia Workbench | iii Console |
+| Node.js + Python | Pure Python |
+
+## Documentation Structure
+
+```
+docs/
+├── INDEX.md                  # This file
+├── ARCHITECTURE.md           # System design (Motia III)
+└── advoware/
+    └── (optional API specs)
+
+steps/{module}/
+├── README.md                 # Module overview
+└── {step_name}_step.py       # Step implementation
+
+services/
+└── {service_name}.py         # Service implementations
+
+MIGRATION_GUIDE.md            # Complete migration guide
+MIGRATION_STATUS.md           # Migration progress
+MIGRATION_COMPLETE_ANALYSIS.md # Final analysis
+```
+
+## Quick Reference
+
+### Common Tasks
+
+| Task | Documentation |
+|------|---------------|
+| Understand migration | [MIGRATION_GUIDE.md](../MIGRATION_GUIDE.md) |
+| Check migration status | [MIGRATION_STATUS.md](../MIGRATION_STATUS.md) |
+| Understand architecture | [ARCHITECTURE.md](ARCHITECTURE.md) |
+| Calendar sync overview | [steps/advoware_cal_sync/README.md](../steps/advoware_cal_sync/README.md) |
+| Proxy API usage | [steps/advoware_proxy/README.md](../steps/advoware_proxy/README.md) |
+| VMH sync details | [steps/vmh/README.md](../steps/vmh/README.md) |
+
+### Code Locations
+
+| Component | Location | Documentation |
+|-----------|----------|---------------|
+| API Proxy Steps | `steps/advoware_proxy/` | [README](../steps/advoware_proxy/README.md) |
+| Calendar Sync Steps | `steps/advoware_cal_sync/` | [README](../steps/advoware_cal_sync/README.md) |
+| VMH Steps | `steps/vmh/` | [README](../steps/vmh/README.md) |
+| Advoware Service | `services/advoware_service.py` | (in-code docs) |
+| Configuration | `iii-config.yaml` | System config |
+| Environment | `.env` or systemd | Environment variables |
+
+## Running the System
+
+### Start iii Engine
+```bash
+cd /opt/motia-iii/bitbylaw
+/opt/bin/iii -c iii-config.yaml
+```
+
+### Start iii Console (Web UI)
+```bash
+/opt/bin/iii-console --enable-flow --host 0.0.0.0 --port 3113 \
+  --engine-host 192.168.67.233 --engine-port 3111 --ws-port 3114
+```
+
+### Access Web Console
+Open browser: `http://localhost:3113/`
+
+### Check Registered Steps
+```bash
+curl http://localhost:3111/_console/functions | python3 -m json.tool
+```
+
+## Testing
+
+### Test HTTP Step
+```bash
+# Calendar sync API
+curl -X POST "http://localhost:3111/advoware/calendar/sync" \
+  -H "Content-Type: application/json" \
+  -d '{"kuerzel": "PB"}'
+
+# Advoware proxy
+curl "http://localhost:3111/advoware/proxy?endpoint=employees"
+```
+
+### Trigger Cron Manually
+```bash
+curl -X POST "http://localhost:3111/_console/cron/trigger" \
+  -H "Content-Type: application/json" \
+  -d '{"function_id": "steps::Calendar Sync Cron Job::trigger::0"}'
+```
+
+### Check Logs
+View logs in iii Console or via API:
+```bash
+curl "http://localhost:3111/_console/logs"
+```
+
+## External Resources
+
+- [Motia III Documentation](https://iii.dev)
+- [Python SDK](https://pypi.org/project/motia/)
+- [Google Calendar API](https://developers.google.com/calendar)
+- [Redis Documentation](https://redis.io/documentation)
+
+## Support
+
+- **Migration Questions**: Check [MIGRATION_GUIDE.md](../MIGRATION_GUIDE.md)
+- **Runtime Issues**: Check iii Console logs
+- **Step Not Showing**: Verify import errors in logs
+- **Redis Issues**: Check Redis connection in `services/`