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
- **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:
```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
# 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
# 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
```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

## Development

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

- [x] Basic project structure and service 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.