initial project setup

docs/specs.md

@@ -0,0 +1,126 @@
+# 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.