195 lines
6.7 KiB
Markdown
195 lines
6.7 KiB
Markdown
# 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** ([Module README](../steps/vmh/README.md)):
|
|
- [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](../services/ADVOWARE_SERVICE.md) - API Client mit HMAC-512 Auth
|
|
- [Advoware API Swagger](advoware/advoware_api_swagger.json) - Vollständige API-Dokumentation (JSON)
|
|
|
|
### 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
|
|
└── advoware/
|
|
└── advoware_api_swagger.json # Advoware API spec
|
|
|
|
steps/{module}/
|
|
├── README.md # Module overview
|
|
└── {step_name}.md # Step documentation
|
|
|
|
services/
|
|
└── {service_name}.md # Service documentation
|
|
|
|
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
|