motia/bitbylaw/README.md

# bitbylaw - Motia Integration Platform

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

## Quick Start

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

Siehe: [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) für Details.

## Komponenten

1. **Advoware API Proxy** - REST-API-Proxy mit HMAC-512 Auth ([Details](steps/advoware_proxy/README.md))
2. **Calendar Sync** - Bidirektionale Synchronisation Advoware ↔ Google ([Details](steps/advoware_cal_sync/README.md))
3. **VMH Webhooks** - EspoCRM Webhook-Receiver für Beteiligte ([Details](steps/vmh/README.md))

## Architektur

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

Siehe: [docs/ARCHITECTURE.md](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](docs/API.md)

## Configuration

Environment Variables via `.env` oder systemd service:

```bash
# 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/CONFIGURATION.md)
- [docs/GOOGLE_SETUP.md](docs/GOOGLE_SETUP.md) - Service Account Setup

## Deployment

Production deployment via systemd:

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

Siehe: [docs/DEPLOYMENT.md](docs/DEPLOYMENT.md)

## Documentation

### Getting Started
- [Development Guide](docs/DEVELOPMENT.md) - Setup, Coding Standards, Testing
- [Configuration](docs/CONFIGURATION.md) - Environment Variables
- [Deployment](docs/DEPLOYMENT.md) - Production Setup

### Technical Details  
- [Architecture](docs/ARCHITECTURE.md) - System Design, Datenflüsse
- [API Reference](docs/API.md) - HTTP Endpoints, Event Topics
- [Troubleshooting](docs/TROUBLESHOOTING.md) - Common Issues

### Components
- [Advoware Proxy](steps/advoware_proxy/README.md) - API Proxy Details
- [Calendar Sync](steps/advoware_cal_sync/README.md) - Sync Logic
- [VMH Webhooks](steps/vmh/README.md) - Webhook Handlers
- [Advoware Service](services/ADVOWARE_SERVICE.md) - 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

```bash
# 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](docs/INDEX.md) - Documentation navigation
- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) - System architecture
- [docs/advoware/advoware_api_swagger.json](docs/advoware/advoware_api_swagger.json) - Advoware API spec
- [scripts/calendar_sync/README.md](scripts/calendar_sync/README.md) - Utility scripts

---

## Testing

```bash
# 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/](docs/)
- **Logs**: `sudo journalctl -u motia.service -f`