motia-iii/docs/INDEX.md

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