sa4cps-frontend/README.md

# Real-Time Energy Monitoring Dashboard

A comprehensive full-stack application for monitoring and managing energy consumption and air quality in smart buildings. The system provides real-time data visualization, room-based analytics, and intelligent recommendations for building management.

## 📋 Project Overview

This application enables facility managers and building operators to:

- **Monitor real-time energy consumption** across multiple sensors and rooms
- **Track air quality (CO2 levels)** with automated status classification
- **Estimate occupancy** based on environmental data patterns
- **Receive intelligent recommendations** for HVAC optimization and ventilation
- **Visualize building-wide metrics** through interactive charts and dashboards
- **Access room-by-room analytics** for targeted energy management

## 🏗️ Architecture

### Frontend (Vue.js 3 + TypeScript)
- **Reactive dashboard** with real-time chart updates
- **Multi-sensor support** with room-based grouping
- **Responsive design** optimized for desktop and mobile
- **State management** via Pinia for efficient data handling

## 🚀 Installation & Setup

### Prerequisites

- **Redis Server**: Must be running on `localhost:6379`
- **Python 3.9+**: Backend runtime
- **Node.js 20.19.0+ or 22.12.0+**: Frontend development

The backend should be available at `http://localhost:8000`

### Frontend Setup

```bash
cd dashboard/frontend

# Install dependencies
npm install

# Start development server
npm run dev

# Additional commands
npm run build        # Production build
npm run type-check   # TypeScript validation
npm run test:unit    # Run unit tests
npm run lint         # ESLint with auto-fix
npm run format       # Prettier formatting
```

The frontend will be available at `http://localhost:5173`

## ✨ Features

### 📊 Real-Time Dashboard
- **Live energy consumption charts** with automatic updates
- **WebSocket-powered data streaming** for zero-latency updates
- **Metric cards** showing current values, totals, and averages
- **Connection status indicators** with visual feedback

### 🏢 Room-Based Analytics
- **Room overview cards** with energy and CO2 metrics per space
- **Occupancy estimation** based on environmental data patterns
- **Color-coded status indicators** for quick visual assessment
- **Sensor grouping** by room for organized data presentation

### 🌬️ Air Quality Monitoring
- **CO2 level classification**:
  - 🟢 **Good**: <400 ppm
  - 🟡 **Moderate**: 400-1000 ppm
  - 🟠 **Poor**: 1000-5000 ppm
  - 🔴 **Critical**: >5000 ppm
- **Building-wide air quality status** with overall health indicators
- **Priority room alerts** sorted by urgency
- **Automated recommendations** for ventilation and HVAC adjustments

### 📱 Responsive Design
- **Mobile-optimized interface** with fixed bottom navigation
- **Desktop hover interactions** for enhanced UX
- **Adaptive layouts** that work across all screen sizes
- **Touch-friendly controls** for mobile interactions

### 📋 Data Management
- **Sensor consumption table** with sortable columns
- **Multi-format data support** (legacy energy-only + enhanced multi-metric)
- **Real-time calculations** for totals, averages, and trends
- **Data buffering** to prevent UI blocking during high-frequency updates

### 🔧 Developer Features
- **TypeScript support** for type-safe development
- **Hot module replacement** for fast development cycles
- **ESLint + Prettier** for consistent code formatting
- **Vitest** for unit testing
- **Vue DevTools** integration

## 📊 Data Formats

### Legacy Format (Energy Only)
```json
{
  "sensorId": "sensor_1",
  "timestamp": 1672531200,
  "value": 2.34,
  "unit": "kWh"
}
```

### Enhanced Format (Multi-Metric)
```json
{
  "sensorId": "sensor_1",
  "room": "Conference Room A",
  "timestamp": 1672531200,
  "energy": {
    "value": 2.34,
    "unit": "kWh"
  },
  "co2": {
    "value": 450,
    "unit": "ppm"
  },
  "temperature": {
    "value": 22.5,
    "unit": "°C"
  }
}
```

## 🔗 Key Endpoints

- **WebSocket**: `ws://localhost:8000/ws` - Real-time data streaming
- **Frontend**: `http://localhost:5173` - Dashboard interface
- **Backend API**: `http://localhost:8000` - FastAPI server

## 🎯 Use Cases

- **Smart Building Management**: Monitor energy usage and air quality across facilities
- **HVAC Optimization**: Receive data-driven recommendations for climate control
- **Occupancy Tracking**: Estimate room usage for space optimization
- **Environmental Compliance**: Track CO2 levels for health and safety requirements
- **Cost Management**: Analyze energy consumption patterns for cost reduction
- **Predictive Maintenance**: Identify equipment issues through anomaly detection

## 🛠️ Technology Stack

**Frontend:**
- Vue.js 3 (Progressive framework)
- TypeScript (Type safety)
- Pinia (State management)
- Vue Router (Client-side routing)
- Vite (Build tool)
- Tailwind CSS (Styling)
- ECharts (Data visualization)
- Vitest (Testing framework)

## 📈 Future Enhancements

- Historical data storage and analysis
- Machine learning predictions for energy consumption
- Integration with building automation systems
- Mobile app for on-the-go monitoring
- Advanced alerting and notification system
- Multi-tenant support for building portfolios
- Energy cost calculation and reporting
- Weather data correlation for HVAC optimization

---

⚡ by gecad for smarter, more efficient buildings.