labFusion/README.md

# 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
- **Dockerized Deployment**: Easy setup with Docker Compose

## Architecture

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

## Quick Start

### Prerequisites

- Docker and Docker Compose
- Git
- Access to container registry (optional, for pre-built images)

### Installation

1. Clone the repository:
```bash
git clone <repository-url>
cd labfusion
```

2. Copy the environment configuration:
```bash
cp env.example .env
```

3. Edit `.env` file with your configuration:
```bash
# Docker Registry Configuration (for pre-built images)
DOCKER_REGISTRY=gittea.kammenstraatha.duckdns.org/admin
DOCKER_USERNAME=admin
IMAGE_TAG=main

# 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:
```bash
# Using pre-built images from registry (recommended)
docker-compose up -d

# Or for development with local builds
docker-compose -f docker-compose.dev.yml up -d
```

**Docker Compatibility Issues?** If you encounter BuildKit cache errors (common with Docker 27.x), run our compatibility fix:

**Windows:**
```powershell
.\scripts\fix-docker-compatibility.ps1
```

**Linux/macOS:**
```bash
./scripts/fix-docker-compatibility.sh
```

See [Docker Compatibility Guide](docs/DOCKER_COMPATIBILITY.md) for detailed troubleshooting.

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
```bash
cd services/api-gateway
mvn spring-boot:run
```

#### Python Service Adapters
```bash
cd services/service-adapters
pip install -r requirements.txt
uvicorn main:app --reload
```

### Frontend Development
```bash
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

## Docker Deployment

LabFusion supports both pre-built images from container registries and local builds:

### Pre-built Images (Recommended)
```bash
# Configure registry settings in .env
DOCKER_REGISTRY=gittea.kammenstraatha.duckdns.org/admin
DOCKER_USERNAME=admin
IMAGE_TAG=main

# Deploy with pre-built images
docker-compose up -d
```

### Local Development
```bash
# Build and run locally
docker-compose -f docker-compose.dev.yml up -d
```

For detailed deployment instructions, see [Docker Deployment Guide](docs/DOCKER_DEPLOYMENT.md).

## Roadmap

- [x] Basic project structure and Docker setup
- [x] Spring Boot API gateway with authentication
- [x] FastAPI service adapters with modular structure
- [x] React frontend with dashboard
- [x] Unified API documentation service
- [x] OpenAPI/Swagger integration
- [x] Frontend clean code refactoring
- [x] 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](LICENSE) file for details.

## Support

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