labFusion/services/service-adapters/README.md

Service Adapters

Python FastAPI service for integrating with external homelab services.

Purpose

• Integrate with Home Assistant, Frigate, Immich, n8n
• Transform external service data into standardized format
• Publish events to the message bus
• Provide unified API for service data

Technology Stack

• Language: Python 3.11
• Framework: FastAPI
• Port: 8000
• Message Bus: Redis
• Documentation: OpenAPI/Swagger

Features

• Home Assistant entity integration
• Frigate event processing
• Immich asset management
• n8n workflow triggers
• Event publishing to Redis
• Comprehensive OpenAPI documentation
• Modular architecture for maintainability

Project Structure

service-adapters/
├── main.py                 # FastAPI application (40 lines)
├── models/
│   ├── schemas.py          # Pydantic models
├── routes/
│   ├── general.py          # Root, health, services
│   ├── home_assistant.py   # HA integration
│   ├── frigate.py          # Frigate integration
│   ├── immich.py           # Immich integration
│   └── events.py           # Event management
└── services/
    ├── config.py           # Service configurations
    └── redis_client.py     # Redis connection

API Endpoints

• GET / - API information
• GET /health - Health check
• GET /services - Service status
• GET /home-assistant/entities - HA entities
• GET /frigate/events - Frigate events
• GET /immich/assets - Immich assets
• POST /publish-event - Publish events
• GET /events - Retrieve events

Development Status

✅ Complete - Core functionality implemented with modular architecture and comprehensive testing

Testing

• Unit Tests: Comprehensive test coverage with pytest
• Coverage: HTML coverage reports in htmlcov/
• Security: Bandit and Safety security scanning
• Quality: Black, isort, flake8, mypy code quality checks
• CI/CD: Automated testing in Gitea Actions pipeline

Clean Code Implementation

• Modular Structure: Separated concerns across models, routes, and services
• Type Safety: Pydantic models with comprehensive validation
• Error Handling: Consistent error responses and proper HTTP status codes
• Documentation: Auto-generated OpenAPI documentation
• Testing: Comprehensive test suite with high coverage
• Code Quality: Automated formatting and linting