HomeGenie - Smart Maintenance Management System

HomeGenie is an AI-powered maintenance management platform designed for residential societies. It enables residents to raise maintenance requests with photos, allows administrators to track and assign tasks, and sends automated email notifications for efficient issue resolution.

---

Application Flow:

1.Register

2.Login

3.Dashboard (Resident)

4.Create New Request(Resident)

5.Dashboard (Admin)

6.Assign Technician

7.Voice Assitant

Email Notifications: User-> Admin (on request creation)

Admin-> Technician (on assigning request)

Admin-> User(on request status update)

Monitoring:

Grafana:

Prometheus:

---

Overview

HomeGenie centralizes the process of handling maintenance requests in residential complexes. It replaces manual communication methods such as WhatsApp or Excel sheets with a structured, automated workflow.

The platform uses AI to classify issues by category and priority and provides real-time status tracking for residents, administrators, and technicians.

Key Problems Addressed

• Manual tracking of maintenance issues
• Lack of visibility into request status
• Missed or delayed handling of urgent problems
• No centralized reporting or accountability

Solution Highlights

• Speech-to-Text: Converts voice commands to text using Google Speech Recognition
• Intent Recognition: Uses Google Gemini / Hugging Face AI to understand user requests
• Centralized management of all maintenance requests
• AI-driven categorization and prioritization
• Email notifications to all stakeholders
• Real-time tracking of progress and completion
• Cloud-based storage for uploaded issue photos

Example Interactions:

User: "My kitchen sink is leaking"
AI: "I've created your maintenance request for a plumbing issue 
     with high priority. Ticket #41 has been submitted."

User: "Emergency! Water flooding my apartment!"
AI: "I've detected an emergency. Creating critical priority ticket 
     immediately. Help is on the way!"

User: "What's the status of my AC repair?"
AI: "Your AC repair request #41 is in progress. Technician 
     will arrive tomorrow between 2-4 PM."

---

Core Features

AI-Based Classification

Example:

User Input: "Urgent! Water leaking from bathroom tap"
AI Output: Category = PLUMBING, Priority = CRITICAL

Automated Email Notifications

Email notifications are automatically sent when:

• A resident creates a new request
• The admin assigns a technician
• A technician updates the request status
• A request is completed

Admin Dashboard

• Displays total requests and their statuses
• Filters by category, priority, and technician
• Real-time updates and analytics

Scheduler for Pending Requests

A background scheduler runs periodically to check for requests that have remained in a Pending state for more than 24 hours.
If such requests are found, the system sends reminder emails to the admin.

Implementation Details:

• The scheduler runs every 2 minutes in test mode (configurable via cron expression)
• It fetches all pending maintenance requests from the database
• For each request older than 24 hours, it retrieves user details from the User Service
• Sends a reminder email to the admin with request details

---

Architecture

React Frontend (Port 3000)
  - User registration and login
  - Request creation and tracking
  - Admin dashboard
  - Technician assignment
        │
        ▼
API Gateway (Port 8080) ─────────────────────────────────────
  │                                                          │
  ├─► User Service (Port 8081)                               │
  │     - Authentication (JWT)                               │
  │     - User management                                    │
  │     - Role-based access control                          │
  │     - Technician directory                               │
  │                                                          │
  ├─► Maintenance Service (Port 8082)                        │
  │     - Request management (CRUD)                          │
  │     - AI classification and priority assignment          │
  │     - Email notifications and scheduling                 │
  │     - Statistics and analytics                           │
  │                                                          │
  └─► Python Voice Service (Port 8000)                       │
        - Speech-to-Text (Google Speech Recognition)         │
        - Text-to-Speech (gTTS)                              │
        - AI Intent Recognition (Gemini 2.0 Flash)           │
─────────────────────────────────────────────────────────────┘

PostgreSQL Databases
  - homegenie_users
  - homegenie_maintenance

AWS Integration
  - S3 for image storage
  - SES for email notifications
  - EC2 for deployment

---

API Gateway

The API Gateway is implemented using Spring Cloud Gateway (free, open-source) and serves as a single entry point for all backend services.

How It Works

1. Single Entry Point: All API requests from the frontend go to http://localhost:8080
2. Route Matching: The gateway matches incoming requests by path patterns
3. Request Forwarding: Requests are forwarded to the appropriate backend service
4. Response Relay: Service responses are relayed back to the frontend

Route Configuration

Route Pattern	Target Service	Port
/api/auth/**	User Service	8081
/api/users/**	User Service	8081
/api/technicians/**	User Service	8081
/api/maintenance/**	Maintenance Service	8082
/api/speech-to-text	Voice Service	8000
/api/text-to-speech	Voice Service	8000
/api/recognize-intent	Voice Service	8000

Benefits

• Simplified Frontend: Frontend only needs to know one URL
• Centralized CORS: CORS handled at gateway level
• Easy Scaling: Add new services without frontend changes
• Future-Ready: Easy to add rate limiting, authentication, logging

---

Tech Stack

Backend

• Spring Boot 3.2.0 (Java 17)
• Spring Cloud Gateway (API Gateway)
• Hibernate / JPA
• PostgreSQL
• JWT Authentication

Frontend

• React 18
• Tailwind CSS
• Lucide React for icons

Cloud & AI

• Hugging Face API for classification
• AWS S3 for image storage
• AWS SES for email delivery
• AWS EC2 for hosting

---

Setup Instructions

Prerequisites

• Java 17+
• Node.js 18+
• PostgreSQL 14+
• AWS account (Free Tier)

Installation

1. Clone the repository:

   git clone https://github.com/yourusername/homegenie.git
   cd homegenie

2. Create PostgreSQL databases:

   sudo -u postgres psql
   CREATE DATABASE homegenie_users;
   CREATE DATABASE homegenie_maintenance;
   \q

3. Configure AWS S3 and SES.

4. Start backend services:

   # API Gateway (Port 8080)
   cd api-gateway
   mvn spring-boot:run
   
   # User Service (Port 8081)
   cd userservice
   mvn spring-boot:run
   
   # Maintenance Service (Port 8082)
   cd maintenanceservice
   mvn spring-boot:run
   
   # Python Voice Service (Port 8000)
   cd maintenanceservice/python-voice-service
   pip install -r requirements.txt
   python main.py

5. Start frontend:

   cd homegenie-app
   npm install
   npm start

   Future Enhancements

• Dedicated Technician Dashboard for task acceptance, status updates, and ETA tracking
• Event-driven notification system to decouple alerts from core business logic
• Multi-channel notifications (Email, SMS, Push) for critical and emergency requests
• Resilience mechanisms (circuit breakers, retries, fallbacks) for external services
• Audit logs & request history for traceability and accountability
• Advanced analytics & predictive insights using historical maintenance data