# Documentation Index

## Getting Started

**New to the project?** Start here:

1. [README.md](../README.md) - Project Overview & Quick Start
2. [DEVELOPMENT.md](DEVELOPMENT.md) - Setup Development Environment
3. [CONFIGURATION.md](CONFIGURATION.md) - Configure Environment Variables

## Core Documentation

### For Developers
- **[DEVELOPMENT.md](DEVELOPMENT.md)** - Complete development guide
  - Setup, Coding Standards, Testing, Debugging
- **[ARCHITECTURE.md](ARCHITECTURE.md)** - System design and architecture
  - Components, Data Flow, Event-Driven Design
- **[API.md](API.md)** - HTTP Endpoints and Event Topics
  - Proxy API, Calendar Sync API, Webhook Endpoints

### For Operations
- **[DEPLOYMENT.md](DEPLOYMENT.md)** - Production deployment
  - Installation, systemd, nginx, Monitoring
- **[CONFIGURATION.md](CONFIGURATION.md)** - Environment configuration
  - All environment variables, secrets management
- **[TROUBLESHOOTING.md](TROUBLESHOOTING.md)** - Problem solving
  - Common issues, debugging, log analysis

### Special Topics
- **[GOOGLE_SETUP.md](GOOGLE_SETUP.md)** - Google Service Account setup
  - Step-by-step guide for Calendar API access

## Component Documentation

### Steps (Business Logic)

**Advoware Proxy** ([Module README](../steps/advoware_proxy/README.md)):
- [advoware_api_proxy_get_step.md](../steps/advoware_proxy/advoware_api_proxy_get_step.md)
- [advoware_api_proxy_post_step.md](../steps/advoware_proxy/advoware_api_proxy_post_step.md)
- [advoware_api_proxy_put_step.md](../steps/advoware_proxy/advoware_api_proxy_put_step.md)
- [advoware_api_proxy_delete_step.md](../steps/advoware_proxy/advoware_api_proxy_delete_step.md)

**Calendar Sync** ([Module README](../steps/advoware_cal_sync/README.md)):
- [calendar_sync_cron_step.md](../steps/advoware_cal_sync/calendar_sync_cron_step.md) - Daily trigger
- [calendar_sync_api_step.md](../steps/advoware_cal_sync/calendar_sync_api_step.md) - Manual trigger
- [calendar_sync_all_step.md](../steps/advoware_cal_sync/calendar_sync_all_step.md) - Employee cascade
- [calendar_sync_event_step.md](../steps/advoware_cal_sync/calendar_sync_event_step.md) - Per-employee sync (complex)

**VMH Webhooks & Sync** ([Module README](../steps/vmh/README.md)):
- **Beteiligte Sync** (Bidirectional EspoCRM ↔ Advoware)
  - [BETEILIGTE_SYNC.md](BETEILIGTE_SYNC.md) - Complete documentation
  - [README_SYNC.md](../steps/vmh/README_SYNC.md) - Event handler docs
  - [beteiligte_sync_event_step.py](../steps/vmh/beteiligte_sync_event_step.py) - Event handler
  - [beteiligte_sync_cron_step.py](../steps/vmh/beteiligte_sync_cron_step.py) - Cron job
- **Webhooks**
  - [beteiligte_create_api_step.md](../steps/vmh/webhook/beteiligte_create_api_step.md) - Create webhook
- [beteiligte_update_api_step.md](../steps/vmh/webhook/beteiligte_update_api_step.md) - Update webhook (similar)
- [beteiligte_delete_api_step.md](../steps/vmh/webhook/beteiligte_delete_api_step.md) - Delete webhook (similar)
- [beteiligte_sync_event_step.md](../steps/vmh/beteiligte_sync_event_step.md) - Sync handler (placeholder)

### Services

- **Advoware Service** ([ADVOWARE_SERVICE.md](../services/ADVOWARE_SERVICE.md)) - API Client mit HMAC-512 Auth
- **Advoware API Swagger** ([advoware_api_swagger.json](advoware/advoware_api_swagger.json)) - Vollständige API-Dokumentation
- **EspoCRM Service** ([espocrm.py](../services/espocrm.py)) - EspoCRM API Client mit X-Api-Key Auth
- **Sync Services**
  - [beteiligte_sync_utils.py](../services/beteiligte_sync_utils.py) - Sync utilities (lock, timestamp, merge)
  - [espocrm_mapper.py](../services/espocrm_mapper.py) - Entity mapping EspoCRM ↔ Advoware

### Sync Documentation

#### 📚 Main Documentation
- **[SYNC_OVERVIEW.md](SYNC_OVERVIEW.md)** - ⭐ **START HERE** - Komplette Sync-Dokumentation
  - System-Architektur (Defense in Depth: Webhook + Cron)
  - Beteiligte Sync (Stammdaten): rowId-basierte Change Detection
  - Kommunikation Sync (Phone/Email/Fax): Hash-basierte Change Detection, 6 Varianten
  - Sync Status Management: 8 Status-Werte, Retry mit Exponential Backoff
  - Bekannte Einschränkungen & Workarounds (Advoware API Limits)
  - Troubleshooting Guide (Duplikate, Lock-Issues, Konflikte)

#### 📁 Archive
- **[archive/](archive/)** - Historische Analysen & Detail-Dokumentationen
  - Original API-Analysen (Kommunikation, Adressen)
  - Code-Reviews & Bug-Analysen
  - Detail-Dokumentationen (vor Konsolidierung)

### Utility Scripts

- [Calendar Sync Scripts](../scripts/calendar_sync/README.md) - Wartung und Debugging
  - `delete_employee_locks.py` - Redis Lock Cleanup
  - `delete_all_calendars.py` - Google Calendar Reset

---

## Documentation Structure

```
docs/
├── INDEX.md                  # This file
├── ARCHITECTURE.md           # System design
├── API.md                    # API reference
├── CONFIGURATION.md          # Configuration
├── DEPLOYMENT.md             # Deployment guide
├── DEVELOPMENT.md            # Development guide
├── GOOGLE_SETUP.md           # Google Calendar setup
├── TROUBLESHOOTING.md        # Debugging guide
├── BETEILIGTE_SYNC.md        # ⭐ Beteiligte sync docs
├── SYNC_TEMPLATE.md          # ⭐ Template for new syncs
├── ENTITY_MAPPING_CBeteiligte_Advoware.md  # Field mappings
└── advoware/
    └── advoware_api_swagger.json  # Advoware API spec

steps/{module}/
├── README.md                 # Module overview
├── README_SYNC.md            # ⭐ Sync handler docs (VMH)
└── {step_name}.md            # Step documentation

services/
├── {service_name}.md         # Service documentation
├── beteiligte_sync_utils.py  # ⭐ Sync utilities
└── espocrm_mapper.py         # ⭐ Entity mapper

scripts/{category}/
├── README.md                 # Script documentation
└── *.py                      # Utility scripts
```

## Documentation Standards

### YAML Frontmatter

Each step documentation includes metadata:

```yaml
---
type: step
category: api|event|cron
name: Step Name
version: 1.0.0
status: active|deprecated|placeholder
tags: [tag1, tag2]
dependencies: [...]
emits: [...]
subscribes: [...]
---
```

### Sections

Standard sections in step documentation:

1. **Zweck** - Purpose (one sentence)
2. **Config** - Motia step configuration
3. **Input** - Request structure, parameters
4. **Output** - Response structure
5. **Verhalten** - Behavior, logic flow
6. **Abhängigkeiten** - Dependencies (services, Redis, APIs)
7. **Testing** - Test examples
8. **KI Guidance** - Tips for AI assistants

### Cross-References

- Use relative paths for links
- Link related steps and services
- Link to parent module READMEs

## Quick Reference

### Common Tasks

| Task | Documentation |
|------|---------------|
| Setup development environment | [DEVELOPMENT.md](DEVELOPMENT.md#setup) |
| Configure environment variables | [CONFIGURATION.md](CONFIGURATION.md) |
| Deploy to production | [DEPLOYMENT.md](DEPLOYMENT.md#installation-steps) |
| Setup Google Calendar | [GOOGLE_SETUP.md](GOOGLE_SETUP.md) |
| Debug service issues | [TROUBLESHOOTING.md](TROUBLESHOOTING.md#service-issues) |
| Understand architecture | [ARCHITECTURE.md](ARCHITECTURE.md) |
| Test API endpoints | [API.md](API.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 Webhook Steps | `steps/vmh/` | [README](../steps/vmh/README.md) |
| Advoware API Client | `services/advoware.py` | [DOC](../services/ADVOWARE_SERVICE.md) |
| Configuration | `config.py` | [CONFIGURATION.md](CONFIGURATION.md) |

## Contributing to Documentation

### Adding New Step Documentation

1. Create `{step_name}.md` next to `.py` file
2. Use YAML frontmatter (see template)
3. Follow standard sections
4. Add to module README
5. Add to this INDEX

### Updating Documentation

- Keep code and docs in sync
- Update version history in step docs
- Update INDEX when adding new files
- Test all code examples

### Documentation Reviews

- Verify all links work
- Check code examples execute correctly
- Ensure terminology is consistent
- Validate configuration examples

## External Resources

- [Motia Framework Docs](https://motia.dev) (if available)
- [Advoware API](https://www2.advo-net.net:90/) (requires auth)
- [Google Calendar API](https://developers.google.com/calendar)
- [Redis Documentation](https://redis.io/documentation)

## Support

- **Questions**: Check TROUBLESHOOTING.md first
- **Bugs**: Document in logs (`journalctl -u motia.service`)
- **Features**: Propose in team discussions
- **Urgent**: Check systemd logs and Redis state