🔧 Shramik — Blue-Collar Worker Marketplace

A two-sided marketplace connecting employers with verified blue-collar workers (plumbers, electricians, carpenters) in India. Built with Spring Boot + Flutter, in a single repo.

Status: Active development. Core auth, worker search, and job booking flow are built. See Roadmap for what's planned but not implemented yet.

---

🏗️ Architecture Overview

Flutter App (Android/iOS)
       │
       │  REST API + WebSocket
       ▼
Spring Boot Backend (Java 17)
       │
       ├── PostgreSQL  (users, jobs, otps)
       └── Redis       (worker availability cache by pincode)

---

📁 Project Structure

This is a single repo containing both the backend and the Flutter app.

shramik/
├── backend/                  ← Spring Boot API
│   ├── src/main/java/com/shramik/
│   │   ├── controller/       ← HTTP endpoints (REST API)
│   │   ├── service/          ← Business logic
│   │   ├── entity/           ← Database tables (JPA)
│   │   ├── repository/       ← Database queries
│   │   ├── security/         ← JWT auth filter
│   │   ├── config/           ← Redis, WebSocket, Security config
│   │   ├── dto/              ← API request/response shapes
│   │   └── enums/            ← Skill types, job status, etc.
│   ├── Dockerfile
│   └── pom.xml
│
├── flutter_app/              ← Flutter mobile app
│   ├── lib/
│   │   ├── main.dart
│   │   ├── models/
│   │   ├── services/         ← API calls
│   │   ├── providers/        ← State management (Provider)
│   │   ├── screens/
│   │   │   ├── auth/         ← Login, OTP screens
│   │   │   ├── worker/       ← Worker dashboard, profile setup
│   │   │   ├── employer/     ← Home, search, booking screens
│   │   │   └── shared/       ← Job detail screen
│   │   └── utils/
│   └── pubspec.yaml
│
└── docker-compose.yml        ← Runs backend + postgres + redis together

---

🚀 Quick Start (Local Development)

Prerequisites

• Java 17+
• Flutter 3.16+
• Docker + Docker Compose

1. Start Backend

docker-compose up --build

This starts PostgreSQL, Redis, and the Spring Boot API on port 8080.

2. Run Flutter App

cd flutter_app
flutter pub get
flutter run

For Android emulator, 10.0.2.2:8080 points to your computer's localhost automatically. For a physical device, update the API base URL in lib/utils/app_constants.dart to your computer's local IP.

⚠️ OTP is currently mocked locally (OTP_MOCK=true) — no real SMS is sent yet. See Roadmap.

---

🔑 API Reference

All protected routes require: Authorization: Bearer <token>

Auth

Method	Endpoint	Body	Description
POST	/api/auth/send-otp	{"phone":"9876543210"}	Send OTP (mocked)
POST	/api/auth/verify-otp	{"phone":"...","otp":"123456","role":"WORKER"}	Verify OTP → JWT

Workers

Method	Endpoint	Description
PUT	/api/workers/profile	Update worker profile
GET	/api/workers/{id}	View worker profile
PATCH	/api/workers/availability?status=AVAILABLE_NOW	Toggle availability
GET	/api/workers/search?skill=PLUMBER&pincode=201001	Search workers

Jobs

Method	Endpoint	Description
POST	/api/jobs	Create booking
PATCH	/api/jobs/{id}/status?status=ACCEPTED	Accept/complete job
POST	/api/jobs/{id}/rate	Rate worker
GET	/api/jobs/worker	Worker's job history
GET	/api/jobs/employer	Employer's job history

---

💡 Key Technical Decisions

Why Redis for worker availability? Searching "plumbers near 201001" would otherwise hit PostgreSQL on every request. Redis caches search results per pincode with a 5-minute TTL, and a @CacheEvict clears the relevant pincode key whenever a worker updates their status. This avoids repeated DB load under concurrent search traffic.

Why WebSocket for job notifications? Polling the backend every few seconds for "any new jobs?" wastes requests and battery. STOMP over WebSocket lets the server push a notification the moment a job is created, so workers see new jobs instantly.

Why JWT over server sessions? Mobile clients don't use browser cookies. JWT is a signed token stored on-device; the server validates the signature without a DB lookup per request, which also makes the backend stateless and easier to scale horizontally later.

Why phone + OTP instead of passwords? Phone number is a universal identity in this user base, and OTP removes the "forgot password" support burden entirely. (Note: OTP delivery is currently mocked for local dev — see Roadmap.)

---

🗺️ Roadmap — not yet built

These are planned, not implemented. Listed here deliberately so the README doesn't overstate the current state of the project.

• Real SMS delivery for OTP (currently mocked — OTP_MOCK=true)
• Platform fee / payment processing logic
• CI/CD pipeline (GitHub Actions for test + deploy)
• Production deployment / hosting
• Real users / pilot testing outside personal use

---

👨‍💻 Author

Awaneet Mishra — @awaneetdecoder