127 lines
4.3 KiB
Markdown
127 lines
4.3 KiB
Markdown
# 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.
|