motia/bitbylaw/docs/INDEX.md

Documentation Index

Getting Started

New to the project? Start here:

1. README.md - Project Overview & Quick Start
2. DEVELOPMENT.md - Setup Development Environment
3. CONFIGURATION.md - Configure Environment Variables

Core Documentation

For Developers

• DEVELOPMENT.md - Complete development guide
  • Setup, Coding Standards, Testing, Debugging
• ARCHITECTURE.md - System design and architecture
  • Components, Data Flow, Event-Driven Design
• API.md - HTTP Endpoints and Event Topics
  • Proxy API, Calendar Sync API, Webhook Endpoints

For Operations

• DEPLOYMENT.md - Production deployment
  • Installation, systemd, nginx, Monitoring
• CONFIGURATION.md - Environment configuration
  • All environment variables, secrets management
• TROUBLESHOOTING.md - Problem solving
  • Common issues, debugging, log analysis

Special Topics

• GOOGLE_SETUP.md - Google Service Account setup
  • Step-by-step guide for Calendar API access

Component Documentation

Steps (Business Logic)

Advoware Proxy (Module README):

• advoware_api_proxy_get_step.md
• advoware_api_proxy_post_step.md
• advoware_api_proxy_put_step.md
• advoware_api_proxy_delete_step.md

Calendar Sync (Module README):

• calendar_sync_cron_step.md - Daily trigger
• calendar_sync_api_step.md - Manual trigger
• calendar_sync_all_step.md - Employee cascade
• calendar_sync_event_step.md - Per-employee sync (complex)

VMH Webhooks & Sync (Module README):

• Beteiligte Sync (Bidirectional EspoCRM ↔ Advoware)
  • BETEILIGTE_SYNC.md - Complete documentation
  • README_SYNC.md - Event handler docs
  • beteiligte_sync_event_step.py - Event handler
  • beteiligte_sync_cron_step.py - Cron job
• Webhooks
  • beteiligte_create_api_step.md - Create webhook
• beteiligte_update_api_step.md - Update webhook (similar)
• beteiligte_delete_api_step.md - Delete webhook (similar)
• beteiligte_sync_event_step.md - Sync handler (placeholder)

Services

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

Sync Documentation

📚 Main Documentation

• 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/ - Historische Analysen & Detail-Dokumentationen
  • Original API-Analysen (Kommunikation, Adressen)
  • Code-Reviews & Bug-Analysen
  • Detail-Dokumentationen (vor Konsolidierung)

Utility Scripts

• Calendar Sync Scripts - 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:

---
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
Configure environment variables	CONFIGURATION.md
Deploy to production	DEPLOYMENT.md
Setup Google Calendar	GOOGLE_SETUP.md
Debug service issues	TROUBLESHOOTING.md
Understand architecture	ARCHITECTURE.md
Test API endpoints	API.md

Code Locations

Component	Location	Documentation
API Proxy Steps	steps/advoware_proxy/	README
Calendar Sync Steps	steps/advoware_cal_sync/	README
VMH Webhook Steps	steps/vmh/	README
Advoware API Client	services/advoware.py	DOC
Configuration	config.py	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 (if available)
• Advoware API (requires auth)
• Google Calendar API
• Redis 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