Case Study - Live Betting

📖 Information

Project Definition

This project implements a real-time live betting application where odds are updated dynamically, users can view current match bulletins, and place bets via RESTful APIs.

• Bulletin Management: Create and display match bulletins with up-to-date odds.
• Bet Slip Operations: Allow customers to place single or multiple bet slips, ensuring odds isolation and timeout handling.

Timeout & Transaction Isolation

• Multi‑Slip Limit: Maximum 500 slips per match.
• Odds Isolation: The odds taken at bet initiation are preserved until transaction completes.
• Timeout Management: Each bet slip operation must complete within 10 seconds (modifiable via configuration).

API Development & Security

• RESTful Principles: All endpoints follow standard HTTP methods and status codes.
• Testing: Unit and integration tests cover all service and controller logic.
• Security: Simple mock via X-Customer-Id header for identifying requesters.
• Investment Limit: Maximum stake per slip is 10000 TL, total allowed = limit × multipleSlipCount.

AOP Logging (LoggerAspectJ)

• Pointcut targets all classes annotated with @RestController.
• @AfterReturning advice logs successful responses (endpoint, method, operation, status, payload).
• @AfterThrowing advice logs exceptions (error type, message, endpoint, method, operation).
• Constructs a LogEntity and persists it via LogService.

REST API Design

Design the RESTful APIs for bulletin management and bet slip operations.

• A. Bulletin Management
  • Create Bulletin (Match Event)
    • Endpoint: POST /api/v1/matches/create
    • Description: Adds a new match to the bulletin.
    • Required Fields:
      • leagueName (String) – Name of the league.
      • homeTeam (String) – Home team name.
      • awayTeam (String) – Away team name.
      • homeWinOdds (Decimal) – Odds for home win.
      • drawOdds (Decimal) – Odds for a draw.
      • awayWinOdds (Decimal) – Odds for away win.
      • startTime (ISO‑8601 DateTime) – Match start time.
    • Response: 201 Created with saved match details.
  • Retrieve Bulletin
    • Endpoint: POST /api/v1/matches/getAllMatches
    • Description: Returns paginated match events; clients should poll or subscribe to updates (odds are simulated to change every second).
    • Parameters: page, size, optional sorting.
    • Response: 200 OK with paginated MatchEventResponse.
• B. Bet Slip Operations
  • Create Bet Slip
    • Endpoint: POST /api/v1/betslips/create
    • Description: Places one or more bet slips for a given match event.
    • Headers: X-Customer-Id – Customer identifier (mocked).
    • Request Body:

      							{
        "eventId": "
      								",
        "betType": "HOME_WIN | DRAW | AWAY_WIN",
        "stake": 100.0,
        "multipleSlipCount": 2,
        "selectedRate": 3.75
      }
      								
      							

    • Behavior:
      • Locks in the current odds; verifies against latest odds and returns 400 Bad Request on mismatch.
      • Ensures per-match limit of 500 total slips.
      • Applies a default 2-second timeout per bet (configurable via bet.slip.timeout).
    • Response: 201 Created with BetSlipResponse.
  • Get Customer Bet Slips
    • Endpoint: POST /api/v1/betslips/getBetSlipsByCustomer
    • Description: Retrieves paginated bet slips for a customer.
    • Headers: X-Customer-Id
    • Request Body: page, size, optional sorting.
    • Response: 200 OK with paginated BetSlipResponse.

Explore Rest APIs

Endpoints Summary

Method	URL	Description	Request Body	Headers/Path	Response
POST	/api/v1/matches/create	Create Bulletin (Match Event)	CreateMatchEventRequest	—	CustomResponse<MatchEventResponse>
POST	/api/v1/matches/getAllMatches	Retrieve Bulletin	MatchPagingRequest	—	CustomResponse<CustomPagingResponse<MatchEventResponse>>
POST	/api/v1/betslips/create	Create Bet Slip	CreateBetSlipRequest	Header: X-Customer-Id	CustomResponse<BetSlipResponse>
POST	/api/v1/betslips/getBetSlipsByCustomer	Get Customer Bet Slips	BetSlipPagingRequest	Header: X-Customer-Id	CustomResponse<CustomPagingResponse<BetSlipResponse>>

Technologies

---

• Java 21
• Spring Boot 3.0
• Restful API
• Open Api (Swagger)
• Maven
• Junit5
• Mockito
• Integration Tests
• Docker
• Docker Compose
• CI/CD (Github Actions)
• Postman
• Prometheus
• Grafana
• Alert Manager
• Sonarqube
• Kubernetes
• JaCoCo (Test Report)
• AOP

Postman

Import postman collection under postman_collection folder

Prerequisites

Define Variable in .env file

LIVE_BETTING_SERVICE_DB_IP=localhost
LIVE_BETTING_DB_PORT=3306
DATABASE_USERNAME={MY_SQL_DATABASE_USERNAME}
DATABASE_PASSWORD={MY_SQL_DATABASE_PASSWORD}

GF_SMTP_ENABLED=true
GF_SMTP_HOST=smtp.gmail.com:587
GF_SMTP_USER={your_gmail_email}
GF_SMTP_PASSWORD={gmail_authentication_password}
GF_SMTP_SKIP_VERIFY=true
GF_SMTP_FROM_ADDRESS={your_gmail_email}


ALERT_RESOLVE_TIMEOUT=5m
SMTP_SMARTHOST=smtp.gmail.com:587
SMTP_FROM={your_gmail_email}
SMTP_AUTH_USERNAME={your_gmail_email}
SMTP_AUTH_PASSWORD={gmail_authentication_password}
SMTP_REQUIRE_TLS=true
ALERT_EMAIL_TO={your_gmail_email}

Open Api (Swagger)

http://localhost:5160/swagger-ui/index.html

---

JaCoCo (Test Report)

After the command named mvn clean install completes, the JaCoCo report will be available at:

target/site/jacoco/index.html

Navigate to the target/site/jacoco/ directory.

Open the index.html file in your browser to view the detailed coverage report.

---

Maven, Docker and Kubernetes Running Process

Maven Run

To build and run the application with Maven, please follow the directions shown below;

$ cd git clone https://github.com/Rapter1990/livebetting.git
$ cd livebetting
$ mvn clean install
$ mvn spring-boot:run

---

Docker Run

The application can be built and run by the Docker engine. The Dockerfile has multistage build, so you do not need to build and run separately.

Please follow directions shown below in order to build and run the application with Docker Compose file;

$ cd livebetting
$ docker-compose up -d

If you change anything in the project and run it on Docker, you can also use this command shown below

$ cd livebetting
$ docker-compose up --build

To monitor the application, you can use the following tools:

• Prometheus:
  Open in your browser at http://localhost:9090
  Prometheus collects and stores application metrics.

• Grafana:
  Open in your browser at http://localhost:3000
  Grafana provides a dashboard for visualizing the metrics.
  Default credentials:

  • Username: admin
  • Password: admin

• AlertManager:
  Open in your browser at http://localhost:9093

Define prometheus data source url, use this link shown below

http://prometheus:9090

Define alertManager data source url, use this link shown below

http://alertmanager:9093

---

Kubernetes Run

To run the application, please follow the directions shown below;

• Start Minikube

$ minikube start

• Open Minikube Dashboard

$ minikube dashboard

• To deploy the application on Kubernetes, apply the Kubernetes configuration file underneath k8s folder

$ kubectl apply -f k8s

• To open Prometheus, click tunnel url link provided by the command shown below to reach out Prometheus

minikube service prometheus-service

• To open Grafana, click tunnel url link provided by the command shown below to reach out Prometheus

minikube service grafana-service

• To open AlertManager, click tunnel url link provided by the command shown below to reach out Prometheus

minikube service alertmanager-service

• Define prometheus data source url, use this link shown below

http://prometheus-service.default.svc.cluster.local:9090

• Define alertmanager data source url, use this link shown below

http://alertmanager-service.default.svc.cluster.local:9093

Define Alert through Grafana

• Go to localhost:9093 for Docker and Go there through minikube service alertmanager-service for Kubernetes
• Define Your Gmail address for Contract Point and determine if test mail is send to its email
• After define jvm micrometer dashboard in Grafana with its id 4701, click Heap Used Panel edit and More -> New Alert Rules
• Define Threshold as input assigning to A with IS ABOVE as 2
• Create a new folder names for 3. Add folder and labels and 4. Set evaluation behaviour
• Define Contract Points for your defined email in 5. Configure notification
• After reaching the threshold value, it triggers to send an alert notification to your defined mail

Alert Manager

• Pre-configured Alert Rules:
  • The alert is pre-defined in the rule file within Prometheus, streamlining your monitoring setup
• Threshold-based Trigger:
  • Once any metric exceeds its designated threshold, the alert is automatically activated
• Instant Email Notifications:
  • Upon triggering, Alert Manager sends an immediate email notification to your defined email, keeping you informed in real time

Sonarqube

• Go to localhost:9000 for Docker and Go there through minikube service sonarqube for Kubernetes
• Enter username and password as admin
• Change password
• Click Create Local Project
• Choose the baseline for this code for the project as Use the global setting
• Click Locally in Analyze Method
• Define Token
• Click Continue
• Copy sonar.host.url and sonar.token (sonar.login) in the properties part in pom.xml
• Run mvn sonar:sonar to show code analysis

---

Docker Image Location

https://hub.docker.com/repository/docker/noyandocker/livebetting/general

Screenshots

Click here to show the screenshots of project

Figure 1

Figure 2

Figure 3

Figure 4

Figure 5

Figure 6

Figure 7

Figure 8

Figure 9

Figure 10

Figure 11

Figure 12

Figure 13

Figure 14

Figure 15

Figure 16

Figure 17

Figure 18

Figure 19

Figure 20

Figure 21

Figure 22

Figure 23

Figure 24

Figure 25

Figure 26

Figure 27

Figure 28

Figure 29

Figure 30

Figure 31

Figure 32

Figure 33

Figure 34

Figure 35

Figure 36

Figure 37

Figure 38

Figure 39

Figure 40

Figure 41

Figure 42

Figure 43

Figure 44

Figure 45

Figure 46

Figure 47

Figure 48

Figure 49

Figure 50

Figure 51

Figure 52

Figure 53

Figure 54

Figure 55

Figure 56

Figure 57

Figure 58

Figure 59

Figure 60

Contributors

• Sercan Noyan Germiyanoğlu