Skip to content

README.md

Latest commit

 

History

History
252 lines (199 loc) · 6.1 KB

README.md

File metadata and controls

252 lines (199 loc) · 6.1 KB

Office Resource Booking System (ORBS)

ORBS is a backend-only microservices system for managing office resources such as meeting rooms, desks, parking slots, and devices. Employees can authenticate, browse resources, create bookings, cancel their own bookings, and receive notification records when booking activity happens. Administrators can manage resources and review system activity.

The project is designed as a portfolio-ready Spring Boot backend that demonstrates practical microservices architecture, clean service boundaries, security, inter-service communication, and local containerized deployment.

What This Project Demonstrates

  • Spring Boot microservices in a single monorepo
  • API Gateway, Eureka service discovery, and centralized configuration
  • JWT authentication with role-based authorization
  • database-per-service architecture
  • synchronous service validation with OpenFeign
  • event-driven processing with Kafka
  • Docker Compose-based local deployment
  • realistic booking rules instead of CRUD-only behavior

Architecture

Client
  |
  v
API Gateway
  |
  +--> Auth Service ---------> auth_db
  +--> Resource Service -----> resource_db
  +--> Booking Service ------> booking_db
  |        |
  |        +--> Feign --> Resource Service
  |        |
  |        +--> Kafka --> Notification Service --> notification_db
  |
  +--> Notification Service

Config Server --> config-repo
Service Registry --> Eureka
PostgreSQL --> separate databases per service
Kafka + ZooKeeper --> async event flow

Services

Service Responsibility Port
service-registry Eureka server for service registration and discovery 8761
config-server Centralized external configuration using local native config 8888
api-gateway Single entry point for client APIs 8080
auth-service Registration, login, JWT issuance, seeded users 8081
resource-service Resource catalog management, filters, admin updates 8082
booking-service Booking creation, cancellation, conflict detection 8083
notification-service Kafka consumer for booking events, notification persistence 8084

Core Business Rules

  • Only ACTIVE resources can be booked.
  • Booking start time must be before end time.
  • Past booking start times are rejected.
  • Booking duration cannot exceed 8 hours.
  • Cancelled bookings do not block future bookings.
  • Only the booking owner or an ADMIN can cancel a booking.

Booking Conflict Detection

A booking is rejected when another non-cancelled booking exists for the same resource and:

existing.startTime < new.endTime
AND
existing.endTime > new.startTime

This handles partial overlap, full overlap, and containment correctly while still allowing adjacent bookings.

Security

Roles:

  • ADMIN
  • EMPLOYEE

JWT contains:

  • userId
  • email
  • role

Admin-only operations:

  • create or update resources
  • change resource status
  • view all bookings
  • view all notifications

Technology Stack

  • Java 17
  • Maven
  • Spring Boot 3
  • Spring Cloud Gateway
  • Eureka
  • Spring Cloud Config
  • Spring Security + JWT
  • Spring Data JPA
  • PostgreSQL
  • OpenFeign
  • Kafka
  • Swagger / OpenAPI
  • Spring Boot Actuator
  • Docker Compose

Default Users

Role Email Password
Admin admin@orbs.com Admin@123
Employee employee1@orbs.com Employee@123
Employee employee2@orbs.com Employee@123

Sample API Flow

  1. Login as employee.
  2. List active resources.
  3. Create a booking for a resource.
  4. View my bookings.
  5. Verify a BOOKING_CREATED notification record exists.
  6. Cancel the booking.
  7. Verify a BOOKING_CANCELLED notification record exists.
  8. Login as admin and test resource management or system-wide views.

Gateway base URL:

http://localhost:8080

Key routes:

  • POST /api/auth/register
  • POST /api/auth/login
  • GET /api/auth/me
  • GET|POST|PUT|PATCH /api/resources/**
  • GET|POST|PATCH /api/bookings/**
  • GET /api/notifications/**

Example Requests

Login:

{
  "email": "employee1@orbs.com",
  "password": "Employee@123"
}

Create booking:

{
  "resourceId": 1,
  "startTime": "2026-03-20T10:00:00",
  "endTime": "2026-03-20T12:00:00",
  "purpose": "Sprint planning"
}

Standard error response:

{
  "timestamp": "2026-03-14T11:30:00Z",
  "status": 409,
  "error": "Conflict",
  "message": "Resource is already booked for the requested time range",
  "path": "/api/bookings"
}

Running Locally

Docker Compose

  1. Make sure Docker Desktop is running.
  2. From the repository root, run:
docker compose up --build -d
  1. Wait until all Spring services are healthy:
docker compose ps
  1. Useful endpoints:
  • Eureka: http://localhost:8761
  • Gateway health: http://localhost:8080/actuator/health

The compose setup starts infrastructure first, then business services, and starts the gateway after downstream services are healthy.

Manual Startup Order

If running services outside Docker, start them in this order:

  1. service-registry
  2. config-server
  3. auth-service
  4. resource-service
  5. notification-service
  6. booking-service
  7. api-gateway

API Documentation And Health

Swagger:

  • http://localhost:8081/swagger-ui.html
  • http://localhost:8082/swagger-ui.html
  • http://localhost:8083/swagger-ui.html
  • http://localhost:8084/swagger-ui.html

Health:

  • http://localhost:8761/actuator/health
  • http://localhost:8888/actuator/health
  • http://localhost:8080/actuator/health
  • http://localhost:8081/actuator/health
  • http://localhost:8082/actuator/health
  • http://localhost:8083/actuator/health
  • http://localhost:8084/actuator/health

Repository Structure

orbs/
|-- api-gateway/
|-- auth-service/
|-- booking-service/
|-- config-repo/
|-- config-server/
|-- docker/
|   `-- postgres/
|-- notification-service/
|-- resource-service/
|-- service-registry/
|-- docker-compose.yml
|-- ORBS.postman_collection.json
|-- pom.xml
`-- README.md

Contact

Chandra Sekhar Vipparla
Email: code.chandrasekhar@gmail.com
LinkedIn: https://www.linkedin.com/in/chandra-sekhar-vipparla/