labFusion/docs/specs.md

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.