LabFusion

A unified dashboard and integration hub for your homelab services. LabFusion provides a centralized view of your Home Assistant, Frigate, Immich, n8n, and other homelab services with real-time monitoring, data correlation, and customizable dashboards.

Features

• Unified Dashboard: Single interface for all homelab services
• Real-time Monitoring: System metrics, service status, and event tracking
• Service Integration: Connect to Home Assistant, Frigate, Immich, n8n, and more
• Data Correlation: Cross-service insights and event correlation
• Customizable Widgets: Build dashboards with charts, tables, and status cards
• Polyglot Architecture: Java Spring Boot API gateway with Python FastAPI adapters
• Multi-Service Architecture: Modular services with clear separation of concerns

Architecture

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   React         │    │   Spring Boot   │    │   FastAPI       │
│   Frontend      │◄──►│   API Gateway   │◄──►│   Adapters      │
│                 │    │                 │    │                 │
└─────────────────┘    └─────────────────┘    └─────────────────┘
                                │                        │
                                ▼                        ▼
                       ┌─────────────────┐    ┌─────────────────┐
                       │   PostgreSQL    │    │     Redis       │
                       │   Database      │    │  Message Bus    │
                       └─────────────────┘    └─────────────────┘

Quick Start

Prerequisites

• Java 17+ (for API Gateway)
• Python 3.9+ (for Service Adapters)
• Node.js 18+ (for Frontend and API Docs)
• Git
• PostgreSQL (for data storage)
• Redis (for message bus)

Installation

1. Clone the repository:

git clone <repository-url>
cd labfusion

2. Copy the environment configuration:

cp env.example .env

3. Edit .env file with your configuration:

# Service Integration URLs (update with your actual service URLs and tokens)
HOME_ASSISTANT_URL=http://homeassistant.local:8123
HOME_ASSISTANT_TOKEN=your-ha-token-here
FRIGATE_URL=http://frigate.local:5000
FRIGATE_TOKEN=your-frigate-token-here
IMMICH_URL=http://immich.local:2283
IMMICH_API_KEY=your-immich-api-key-here

4. Start the services:

# Start API Gateway (Java Spring Boot)
cd services/api-gateway
./mvnw spring-boot:run

# Start Service Adapters (Python FastAPI)
cd services/service-adapters
python -m uvicorn main:app --reload --port 8000

# Start Frontend (React)
cd frontend
npm start

# Start API Docs (Node.js Express)
cd services/api-docs
npm start

5. Access the application:

• Frontend: http://localhost:3000
• API Gateway: http://localhost:8080
• Service Adapters: http://localhost:8000
• API Documentation: http://localhost:8083

Services

API Gateway (Spring Boot)

• Port: 8080
• Purpose: Core API, authentication, user management
• Database: PostgreSQL
• Features: JWT authentication, dashboard management, event storage

Service Adapters (FastAPI)

• Port: 8000
• Purpose: Integration with external services
• Features: Home Assistant, Frigate, Immich, n8n integrations

Frontend (React)

• Port: 3000
• Purpose: Dashboard UI
• Features: Real-time updates, customizable widgets, responsive design, offline mode, clean code architecture

Database (PostgreSQL)

• Port: 5432
• Purpose: Persistent storage
• Data: Users, dashboards, widgets, events, device states

Message Bus (Redis)

• Port: 6379
• Purpose: Inter-service communication
• Features: Event publishing, real-time updates

API Documentation (Node.js)

• Port: 8083
• Purpose: Unified API documentation
• Features: Swagger UI, service health monitoring, dynamic spec generation

Development

Backend Development

Java API Gateway

cd services/api-gateway
mvn spring-boot:run

Python Service Adapters

cd services/service-adapters
pip install -r requirements.txt
uvicorn main:app --reload

Frontend Development

cd frontend
npm install
npm start

Configuration

Service Integration

1. Home Assistant:

   • Get your token from Profile → Long-lived access tokens
   • Update HOME_ASSISTANT_URL and HOME_ASSISTANT_TOKEN in .env

2. Frigate:

   • Get your API key from Frigate settings
   • Update FRIGATE_URL and FRIGATE_TOKEN in .env

3. Immich:

   • Get your API key from Immich settings
   • Update IMMICH_URL and IMMICH_API_KEY in .env

Dashboard Customization

• Access the Settings page to configure service integrations
• Use the dashboard builder to create custom layouts
• Add widgets for different data sources and visualizations

API Documentation

• Unified Documentation: http://localhost:8083
• API Gateway: http://localhost:8080/swagger-ui.html
• Service Adapters: http://localhost:8000/docs

Development

Local Development Setup

# Start PostgreSQL and Redis (using your preferred method)
# Then start each service in separate terminals:

# Terminal 1: API Gateway
cd services/api-gateway
./mvnw spring-boot:run

# Terminal 2: Service Adapters  
cd services/service-adapters
python -m uvicorn main:app --reload --port 8000

# Terminal 3: Frontend
cd frontend
npm start

# Terminal 4: API Docs
cd services/api-docs
npm start

Roadmap

• Basic project structure and service setup
• Spring Boot API gateway with authentication
• FastAPI service adapters with modular structure
• React frontend with dashboard
• Unified API documentation service
• OpenAPI/Swagger integration
• Frontend clean code refactoring
• Offline mode and error resilience
• Home Assistant integration
• Frigate integration
• Immich integration
• Real-time WebSocket updates
• Advanced dashboard builder
• Data correlation engine
• Notification system
• Kubernetes deployment

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

For questions and support, please open an issue on GitHub.