HandyMany – Real-Time Service Hiring Platform

HandyMany is a real-time, backend-heavy service hiring platform that connects customers with nearby skilled workers (plumbers, electricians, carpenters, painters, cleaners, AC technicians, etc.) instantly.

The project is inspired by real-world systems like Uber, Ola, and Zomato, but applied to the on-demand local services domain, with a strong focus on backend architecture, real-time communication, and system design.

This project is built to demonstrate production-grade backend engineering, not just basic CRUD APIs.

---

🧩 Problem Statement

Hiring local service workers today is often:

• Manual and slow
• Dependent on phone calls or middlemen
• Uncertain in terms of availability and response time

From the worker’s side:

• Job discovery is inefficient
• No real-time visibility of nearby opportunities
• Unfair competition for the same job

HandyMany solves this using a real-time, backend-driven job matching system that ensures speed, fairness, and clarity for both clients and workers.

---

🎯 Project Overview

HandyMany enables:

• Clients to request services instantly
• The backend to dynamically find suitable workers
• Workers to receive real-time job notifications
• Immediate confirmation when a worker is assigned

The system is designed around:

• Low-latency communication
• Backend-controlled state transitions
• Event-driven architecture
• Clean separation of responsibilities

---

🚀 Key Features & Highlights

🔴 Real-Time Job Matching

• Jobs are pushed to eligible workers via WebSockets (STOMP)
• Workers can claim, reject, or wait
• First valid claim wins (race-condition safe)

🔐 Stateless & Secure Authentication

• JWT-based authentication
• Role-based access (CLIENT, WORKER)
• Secured REST APIs and WebSocket connections

📡 Live Notifications

• Workers receive instant job alerts
• Clients receive real-time updates when:
  • Worker is found
  • Job is assigned
  • Job state changes

🧠 Backend-Driven State Machine

• Job lifecycle fully controlled by backend:
  • SEARCHING
  • WORKER_FOUND
  • ASSIGNED
  • IN_PROGRESS
  • COMPLETED
• Frontend reacts to backend state only

🖥️ System-Level Hardware Checks

• Camera detection
• Device validation
• Sensor availability checks
• Inspired by real-world proctoring systems

🧱 Clean & Scalable Architecture

• Clear separation of:
  • Controllers
  • Services
  • Managers
  • Real-time handlers
• Designed for future scalability

---

Core Components

• Client Application – Requests jobs and listens for updates
• Worker Application – Receives and claims job notifications
• Backend Services – Matching logic, validation, state transitions
• WebSocket Layer – Real-time, user-specific messaging
• Database – Persistent job, user, and worker state

---

⚙️ Tech Stack & Purpose

Backend

• Java + Spring Boot
  Core backend framework for REST APIs, dependency injection, and lifecycle management.

• Spring Security
  Stateless authentication using JWT and role-based authorization.

• WebSockets (STOMP)
  Enables real-time bidirectional communication without polling.

• PostgreSQL
  Reliable relational database for consistent job and user state.

• JPA / Hibernate
  ORM for clean entity modeling and persistence.

Frontend

• React (Vite)
  Fast, component-based frontend with instant rebuilds.

• Context API
  Manages authentication, job state, and WebSocket events.

• Tailwind CSS
  Utility-first styling for a clean, modern UI.

Supporting Concepts & Tools

• JWT
• Axios
• STOMP Client
• Event-driven architecture
• State machines
• System-level programming concepts

---

🔄 How the System Works (End-to-End)

1️⃣ Client Requests a Job

• Client selects a service category
• Request is sent to backend via REST API

2️⃣ Backend Matches Workers

• Workers are filtered based on:
  • Availability
  • Skill
  • Job constraints
• Job is created only after a worker match is found

3️⃣ Real-Time Job Broadcast

• Backend sends WebSocket notifications to eligible workers

4️⃣ Worker Claims the Job

• Workers can claim or reject
• Backend ensures only one worker is assigned

5️⃣ Client Receives Confirmation

• Client receives a JOB_ASSIGNED event
• UI transitions automatically based on backend state

---

🧠 Why This Project Matters

This project demonstrates:

• Real-time system design
• Backend-driven workflows
• Race-condition handling
• Secure WebSocket communication
• Clean architecture principles
• System-level checks beyond web APIs

It reflects how real production systems are designed and operated.

---

🔮 Future Enhancements

• Geo-based worker matching with radius expansion
• Dynamic pricing and bidding
• Job history and analytics
• Ratings and reviews
• Redis for coordination
• Kafka for event streaming
• Microservices decomposition
• Mobile app support

---

👨‍💻 Author

Sumit Kumar
Java Backend Developer | Spring Boot | Real-Time Systems

This project represents my interest in building scalable, real-world backend systems and understanding how production platforms work internally.

---

⭐ If you find this project interesting, feel free to star the repository or reach out!