# Project Specification: **LabFusion**

## 1. Purpose & Goals

* Provide a **unified application** that integrates data and metrics from multiple homelab services (Home Assistant, Frigate, Immich, n8n, etc.).
* Enable creation of **dashboards** that visualize system and service performance (CPU, RAM, storage, uptime, etc.).
* Support **data mashups** (cross-service insights, e.g., "Frigate detected a person → check HA presence → enrich with Immich images").
* Serve as a **learning playground** for:

  * Running **polyglot microservices** (Python, Java/Spring, modern frontend).
  * Hosting everything with **Docker Compose** (extendable to Kubernetes later).
  * Building **APIs and integrations** across services.

---

## 2. User Stories

### Core / First Iteration

* As a homelab owner, I want to see a **system dashboard** that shows CPU, RAM, and storage usage of all devices (Docker host, NAS, etc.).
* As a homelab owner, I want to see the **status of each service** (running, uptime, logs, alerts).
* As a homelab owner, I want to have a **dashboard builder** (predefined widgets like charts, tables, logs).

### Advanced / Later Iterations

* As a homelab owner, I want to **combine service data** (e.g., Frigate face detection + HA presence info).
* As a homelab owner, I want **notifications** (e.g., service down, high CPU, suspicious camera activity).
* As a homelab owner, I want the app to expose an **API layer** that other tools (like n8n) can consume.

---

## 3. Functional Requirements

1. **System Monitoring**

   * Collect metrics from Docker hosts & containers (CPU, memory, disk, network).
   * Display service health (via APIs, logs, or container status).

2. **Service Integrations**

   * **Home Assistant**: read entity states via its REST/WebSocket API.
   * **Frigate**: consume event data (detections, timelines).
   * **Immich**: access image metadata (faces, tags, time).
   * **n8n**: optional integration (trigger workflows from events).

3. **Dashboards**

   * Modular widget-based UI (charts, tables, cards).
   * Configurable dashboards (JSON schema for layout).
   * Examples:

     * Host performance overview.
     * Container uptime.
     * HA device states.
     * Frigate detections timeline.

4. **Data Correlation (Phase 2)**

   * Join data across services.
   * Example: *Frigate detected “Alice” at 18:42 → HA shows Alice’s phone connected → Confirm Alice was home.*

---

## 4. Non-Functional Requirements

* **Performance**: Handle \~1000 events/day without lag.
* **Scalability**: Add more services without rewriting core.
* **Security**: Local auth (JWT/OAuth2), role-based access (later).
* **Resilience**: Auto-restart containers, graceful error handling.
* **Extensibility**: Plugin-like integration architecture.

---

## 5. System Architecture

* **Frontend (React, Vue, or Svelte)**

  * Dashboard UI (charts, cards, widgets).
  * Talks to backend via REST/WebSocket API.

* **Backend (polyglot)**

  * **Java/Spring Boot**: Core API gateway, auth, user management.
  * **Python FastAPI**: Service integration adapters (HA, Frigate, Immich).
  * **Shared Message Bus** (e.g., Redis, Kafka, or RabbitMQ): decouple services.
  * **Database**: PostgreSQL (persistent config, dashboards, event history).

* **Dockerized Deployment**

  * Each component in its own container.
  * Docker Compose orchestrates services.
  * Future upgrade path: Kubernetes.

---

## 6. Data Model (simplified)

* **User** (id, username, roles).
* **Dashboard** (id, name, layout, widgets).
* **Widget** (id, type, config, service binding).
* **Event** (timestamp, service, type, metadata).
* **Device/Service State** (timestamp, entity\_id, value).

---

## 7. Deployment & Operations

* **Docker Compose stack** (frontend, Spring API, FastAPI adapters, DB, Redis).
* CI/CD pipeline (GitHub Actions).
* Monitoring (Prometheus + Grafana, optional since you’re building dashboards).
* Config via `.env` or centralized config service.

---

## Roadmap

* **Iteration 1**: Build basic dashboards with host & container metrics.
* **Iteration 2**: Add service integrations (HA, Frigate).
* **Iteration 3**: Implement cross-service correlations (the "Alice detection" scenario).
* **Iteration 4**: Add notifications & automations.

---

## Project Title

**LabFusion** – a unified dashboard and integration hub for your homelab.