ExpertShadow

A platform where people can book a day shadowing a real professional in their actual work environment.

How to Run

# Clone the project then run
./mvnw spring-boot:run

The app starts on http://localhost:8080

H2 database console: http://localhost:8080/h2-console

• JDBC URL: jdbc:h2:mem:expertshadow
• Username: sa
• Password: (leave blank)

---

The Flow

1. Register a user
2. Apply to be an expert
3. Admin approves the expert
4. Expert creates a listing
5. Expert posts a job day under that listing
6. A different user (guest) books that job day
7. Expert confirms the booking
8. Either party can cancel

---

API Endpoints

Users

Method	URL	What it does
POST	/api/users/register	Register a new user
GET	/api/users	Get all users
GET	/api/users/{id}	Get a user
POST	/api/users/{id}/apply-expert	Apply to become an expert
PATCH	/api/users/{id}/approve	Approve expert application
PATCH	/api/users/{id}/reject	Reject expert application

Listings

Method	URL	What it does
POST	/api/listings?userId=1	Create a listing (verified experts only)
GET	/api/listings	Get all listings
GET	/api/listings/active	Get active listings only
GET	/api/listings/{id}	Get a listing
GET	/api/listings/user/{userId}	Get listings by expert
PATCH	/api/listings/{id}/status?status=PAUSED	Update listing status

Job Days

Method	URL	What it does
POST	/api/job-days?listingId=1	Post a job day
GET	/api/job-days/{id}	Get a job day
GET	/api/job-days/listing/{listingId}	All job days for a listing
GET	/api/job-days/listing/{listingId}/upcoming	Only upcoming open job days
PATCH	/api/job-days/{id}/cancel	Cancel a job day

Bookings

Method	URL	What it does
POST	/api/bookings	Request a booking
GET	/api/bookings/{id}	Get a booking
GET	/api/bookings/user/{userId}	All bookings by a user
GET	/api/bookings/job-day/{jobDayId}	All bookings on a job day
PATCH	/api/bookings/{id}/status	Update booking status
GET	/api/bookings/{id}/allowed-transitions	What transitions are valid now

---

Example Usage

1. Register a user

POST /api/users/register
{
  "name": "Sarah Chen",
  "email": "sarah@example.com",
  "password": "password123",
  "bio": "Food writer and wine enthusiast"
}

2. Apply to be an expert

POST /api/users/1/apply-expert
{
  "profession": "Winemaker",
  "bio": "Third generation winemaker in Napa Valley"
}

3. Approve the expert

PATCH /api/users/1/approve

4. Create a listing

POST /api/listings?userId=1
{
  "title": "A Day in the Winery",
  "description": "Spend a full day working alongside me in the winery",
  "category": "Food & Drink",
  "durationHours": 8,
  "location": "Napa Valley, CA"
}

5. Post a job day

POST /api/job-days?listingId=1
{
  "date": "2026-09-08",
  "description": "Full barrel tasting and blending session",
  "availableSpots": 2,
  "price": 200.00
}

6. Register a second user (the guest)

POST /api/users/register
{
  "name": "Marcus Williams",
  "email": "marcus@example.com",
  "password": "password123"
}

7. Guest books the job day

POST /api/bookings
{
  "jobDayId": 1,
  "userId": 2,
  "guestNote": "I am writing a book about natural wine and would love to learn from you"
}

8. Expert confirms the booking

PATCH /api/bookings/1/status
{
  "status": "CONFIRMED"
}

9. Cancel a booking

PATCH /api/bookings/1/status
{
  "status": "CANCELLED",
  "cancellationReason": "Scheduling conflict"
}

---

Booking Status Rules

REQUESTED  →  CONFIRMED  (expert accepts)
REQUESTED  →  CANCELLED  (either party cancels before confirmation)
CONFIRMED  →  CANCELLED  (either party cancels after confirmation)
CANCELLED  →  nothing    (final state, cannot be changed)

---

Business Rules

• Only verified experts can create listings and post job days
• A guest cannot book their own job day
• A guest cannot book a job day that is full
• A guest cannot book the same job day twice
• Job day dates must be in the future
• Price is locked at booking time even if the job day price changes later
• Remaining spots are calculated in real time from actual bookings