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.

Backend Endpoints

# Complete Energy Management System Overview

## 🏆 **Successfully Integrated: Original Dashboard + tiocps + Microservices**

This implementation successfully combines:
- **Original Dashboard**: Sensor management, room creation, real-time data, analytics
- **tiocps/iot-building-monitoring**: Advanced energy features, IoT control, demand response
- **Modern Architecture**: Microservices, containerization, scalability

## 🏗️ **Complete Architecture (8 Services)**

```
                    🌐 Frontend Applications
                           │
                    ┌──────▼──────┐
                    │ API Gateway │ ← Single Entry Point
                    │   (8000)    │   Authentication & Routing
                    └──────┬──────┘
                           │
          ┌────────────────┼────────────────┐
          │                │                │
    ┌─────▼─────┐   ┌─────▼─────┐   ┌─────▼─────┐
    │  Token    │   │  Sensor   │   │  Battery  │
    │ Service   │   │ Service   │   │ Service   │
    │  (8001)   │   │  (8007)   │   │  (8002)   │
    │           │   │           │   │           │
    │• JWT Auth │   │• Sensors  │   │• Charging │
    │• Permissions│ │• Rooms    │   │• Health   │
    │• Resources│   │• Analytics│   │• Control  │
    └───────────┘   │• WebSocket│   └───────────┘
                    │• Export   │
                    └───────────┘
          │                │                │
    ┌─────▼─────┐   ┌─────▼─────┐   ┌─────▼─────┐
    │ Demand    │   │    P2P    │   │ Forecast  │
    │ Response  │   │  Trading  │   │ Service   │
    │  (8003)   │   │  (8004)   │   │  (8005)   │
    │           │   │           │   │           │
    │• Grid     │   │• Market   │   │• ML Models│
    │• Events   │   │• Trading  │   │• Predict  │
    │• Load Mgmt│   │• P2P Trans│   │• Analysis │
    └───────────┘   └───────────┘   └───────────┘
                           │
                    ┌─────▼─────┐
                    │    IoT    │
                    │ Control   │
                    │  (8006)   │
                    │           │
                    │• Devices  │
                    │• Automation│
                    │• Instructions│
                    └───────────┘
                           │
          ┌────────────────┼────────────────┐
          │                │                │
    ┌─────▼─────┐   ┌─────▼─────┐   ┌─────▼─────┐
    │ MongoDB   │   │   Redis   │   │  WebSocket │
    │ Database  │   │  Cache &  │   │ Real-time  │
    │   (27017) │   │  Events   │   │ Streaming  │
    └───────────┘   │  (6379)   │   └───────────┘
                    └───────────┘
```

## 📋 **Service Inventory & Capabilities**

### **🚪 API Gateway (Port 8000)**
**Role**: Central entry point and orchestration
**Key Features**:
- Request routing to all services
- JWT token validation
- Load balancing and health checks
- Rate limiting and monitoring
- WebSocket proxy for real-time data

**Endpoints**:
```
GET  /health                    # System health
GET  /services/status          # All services status
GET  /stats                    # Gateway statistics
GET  /api/v1/overview          # Complete system overview
WS   /ws                       # WebSocket proxy
```

### **🔐 Token Service (Port 8001)**
**Role**: Authentication and authorization
**Key Features**:
- JWT token generation and validation
- Resource-based permissions
- Token lifecycle management
- Auto-expiration and cleanup

**Endpoints**:
```
POST /tokens/generate          # Create JWT token
POST /tokens/validate          # Verify token
POST /tokens/save             # Store token
POST /tokens/revoke           # Revoke token
GET  /tokens                  # List tokens
```

### **📊 Sensor Service (Port 8007) - 🎯 CORE DASHBOARD**
**Role**: Complete original dashboard functionality + enhancements
**Key Features**:
- **Sensor Management**: CRUD operations, metadata, status
- **Room Management**: Room creation, metrics, occupancy
- **Real-time Data**: WebSocket streaming, live updates
- **Analytics**: Energy consumption, environmental metrics
- **Data Export**: Historical data, multiple formats
- **Event Management**: System alerts, notifications

**Endpoints**:
```
# Original Dashboard APIs (Enhanced)
GET/POST/PUT/DELETE /sensors/*     # Sensor management
GET/POST /rooms/*                  # Room management
WS  /ws                           # Real-time WebSocket
POST /data/query                  # Advanced analytics
GET  /analytics/summary           # System analytics
GET  /export                      # Data export
GET  /events                      # System events

# Enhanced Features
POST /data/ingest                 # Real-time data ingestion
GET  /analytics/energy            # Energy-specific analytics
GET  /rooms/{name}/data          # Room historical data
```

### **🔋 Battery Service (Port 8002)**
**Role**: Energy storage management
**Key Features**:
- Battery monitoring and control
- Charging/discharging optimization
- Health monitoring and alerts
- Performance analytics

**Endpoints**:
```
GET  /batteries                  # All batteries
POST /batteries/{id}/charge      # Charge battery
POST /batteries/{id}/discharge   # Discharge battery
POST /batteries/{id}/optimize    # Smart optimization
GET  /batteries/analytics/summary # System analytics
```

### **⚡ Demand Response Service (Port 8003)**
**Role**: Grid interaction and load management
**Key Features**:
- Demand response event management
- Load reduction coordination
- Flexibility forecasting
- Auto-response configuration

**Endpoints**:
```
POST /invitations/send           # Send DR invitation
GET  /invitations/unanswered     # Pending invitations
POST /invitations/answer         # Respond to invitation
GET  /flexibility/current        # Available flexibility
POST /load-reduction/execute     # Execute load reduction
```

### **🤝 P2P Trading Service (Port 8004)**
**Role**: Peer-to-peer energy marketplace
**Key Features**:
- Energy trading marketplace
- Bid/ask management
- Transaction processing
- Market analytics

### **📈 Forecasting Service (Port 8005)**
**Role**: ML-based predictions
**Key Features**:
- Consumption/generation forecasting
- Historical data analysis
- Model training and optimization
- Predictive analytics

### **🏠 IoT Control Service (Port 8006)**
**Role**: Device management and automation
**Key Features**:
- Device registration and control
- Automation rules and scheduling
- Remote device instructions
- Integration with other services

## 🔄 **Complete API Reference**

### **Original Dashboard APIs (Preserved & Enhanced)**
All original dashboard functionality is preserved and enhanced:

```typescript
// Sensor Management - Now with tiocps enhancements
GET    /api/v1/sensors
POST   /api/v1/sensors
PUT    /api/v1/sensors/{id}
DELETE /api/v1/sensors/{id}
GET    /api/v1/sensors/{id}/data

// Room Management - Now with energy flexibility
GET    /api/v1/rooms
POST   /api/v1/rooms
GET    /api/v1/rooms/{name}
GET    /api/v1/rooms/{name}/data

// Real-time Data - Enhanced with multi-metrics
WebSocket /ws

// Analytics - Enhanced with energy management
GET    /api/v1/analytics/summary
GET    /api/v1/analytics/energy
POST   /api/v1/data/query

// Data Export - Enhanced with all sensor types
GET    /api/v1/export

// System Events - Integrated with all services
GET    /api/v1/events
```

### **New tiocps-based APIs**
Complete energy management capabilities:

```typescript
// Authentication (New)
POST   /api/v1/tokens/generate
POST   /api/v1/tokens/validate

// Battery Management (New)
GET    /api/v1/batteries
POST   /api/v1/batteries/{id}/charge
GET    /api/v1/batteries/analytics/summary

// Demand Response (New)
POST   /api/v1/demand-response/invitations/send
GET    /api/v1/demand-response/flexibility/current

// P2P Trading (New)
POST   /api/v1/p2p/transactions
GET    /api/v1/p2p/market/status

// Forecasting (New)
GET    /api/v1/forecast/consumption
GET    /api/v1/forecast/generation

// IoT Control (New)
POST   /api/v1/iot/devices/{id}/instructions
GET    /api/v1/iot/devices/summary
```

## 🚀 **Deployment & Usage**

### **Quick Start**
```bash
# Clone and navigate
cd microservices/

# Deploy complete system
./deploy.sh deploy

# Check system status
./deploy.sh status

# View logs
./deploy.sh logs
```

### **Service Access Points**
```
🌐 API Gateway:      http://localhost:8000
🔐 Authentication:   http://localhost:8001
📊 Sensors/Rooms:    http://localhost:8007
🔋 Batteries:        http://localhost:8002
⚡ Demand Response:  http://localhost:8003
🤝 P2P Trading:     http://localhost:8004
📈 Forecasting:     http://localhost:8005
🏠 IoT Control:     http://localhost:8006

📡 WebSocket:        ws://localhost:8007/ws
📈 System Health:    http://localhost:8000/health
📊 System Overview:  http://localhost:8000/api/v1/overview
```

### **Example Usage**

**1. Complete Dashboard Workflow (Original + Enhanced)**
```bash
# 1. Get authentication token
TOKEN=$(curl -s -X POST "http://localhost:8000/api/v1/tokens/generate" \
  -H "Content-Type: application/json" \
  -d '{"name": "dashboard_user", "list_of_resources": ["sensors", "rooms", "analytics"]}' \
  | jq -r '.token')

# 2. Create a room
curl -X POST "http://localhost:8000/api/v1/rooms" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Conference Room A", "floor": "2nd", "capacity": 20}'

# 3. Register sensors
curl -X POST "http://localhost:8000/api/v1/sensors" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sensor_id": "TEMP_001",
    "name": "Conference Room Temperature",
    "sensor_type": "temperature",
    "room": "Conference Room A"
  }'

# 4. Get real-time analytics
curl "http://localhost:8000/api/v1/analytics/summary" \
  -H "Authorization: Bearer $TOKEN"

# 5. Export data
curl "http://localhost:8000/api/v1/export?start_time=1704067200&end_time=1704153600" \
  -H "Authorization: Bearer $TOKEN"
```

**2. Advanced Energy Management (New tiocps Features)**
```bash
# Battery management
curl -X POST "http://localhost:8000/api/v1/batteries/BATT001/charge" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"power_kw": 50, "duration_minutes": 120}'

# Demand response event
curl -X POST "http://localhost:8000/api/v1/demand-response/invitations/send" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "event_time": "2024-01-10T14:00:00Z",
    "load_kwh": 100,
    "duration_minutes": 60,
    "iots": ["DEVICE_001", "DEVICE_002"]
  }'

# Get system flexibility
curl "http://localhost:8000/api/v1/demand-response/flexibility/current" \
  -H "Authorization: Bearer $TOKEN"
```

## 📊 **System Monitoring**

### **Health Monitoring**
```bash
# Overall system health
curl http://localhost:8000/health

# Individual service health
curl http://localhost:8001/health  # Token Service
curl http://localhost:8007/health  # Sensor Service
curl http://localhost:8002/health  # Battery Service
# ... etc for all services
```

### **Performance Monitoring**
```bash
# API Gateway statistics
curl http://localhost:8000/stats

# Service status overview
curl http://localhost:8000/services/status

# Complete system overview
curl http://localhost:8000/api/v1/overview
```

## 🎯 **Key Integration Success Factors**

### **✅ Backward Compatibility**
- All original dashboard APIs preserved
- Existing frontend applications work unchanged
- Gradual migration path available

### **✅ Enhanced Functionality**
- Original sensors enhanced with tiocps capabilities
- Room metrics include energy and flexibility data
- Analytics enhanced with energy management insights

### **✅ Scalability & Reliability**
- Independent service scaling
- Fault isolation between services
- Health checks and automatic recovery
- Load balancing and connection pooling

### **✅ Developer Experience**
- Single-command deployment
- Unified API documentation
- Consistent error handling
- Comprehensive logging

### **✅ Production Readiness**
- Docker containerization
- Service discovery and health checks
- Authentication and authorization
- Monitoring and alerting capabilities

## 🔮 **Future Enhancements**

The integrated system provides a solid foundation for:
- **Kubernetes deployment** for cloud-native scaling
- **Advanced ML models** for energy optimization
- **Mobile applications** using the unified API
- **Third-party integrations** via standardized APIs
- **Multi-tenant support** with enhanced authentication

This complete integration successfully delivers a production-ready energy management platform that combines the best of dashboard usability with advanced energy management capabilities, all built on a modern, scalable microservices architecture.