✅ Prerequisites

Before running this project, make sure you have installed:

• Java 21 or higher
• Maven 3.9+ (or use the included Maven Wrapper mvnw)
• Docker Desktop (for PostgreSQL and RabbitMQ)
• Git
• An IDE such as IntelliJ IDEA (recommended)

🚀 Setup and Installation

1. Clone the Repository

git clone https://github.com/CSCI44092GroupProject/order-service.git
cd order-service

2. Create the .env File

Copy the template and fill in your local values:

cp .env.example .env

Contents of .env:

# Local PostgreSQL (Docker)
DB_HOST=localhost
DB_PORT=5432
DB_NAME=order_db
DB_USERNAME=order_user
DB_PASSWORD=change_me

# RabbitMQ (Docker)
RABBITMQ_HOST=localhost
RABBITMQ_PORT=5672
RABBITMQ_USERNAME=rabbitmq_user
RABBITMQ_PASSWORD=rabbitmq_password

3. Start Docker Containers

Start PostgreSQL and RabbitMQ:

docker compose up -d

Verify both containers are running:

docker ps

You should see order-postgres and order-rabbitmq in the output.

🏃 Running the Application

Option 1 — From IntelliJ

1. Open the project in IntelliJ IDEA
2. Right-click OrderServiceApplication.java
3. Click Run 'OrderServiceApplication'

Option 2 — From Terminal

./mvnw spring-boot:run

The application will start on http://localhost:8080.

📖 API Documentation

Once the application is running, access the interactive API documentation:

• Swagger UI: http://localhost:8080/swagger-ui.html
• OpenAPI JSON: http://localhost:8080/v3/api-docs

Example Request

POST /api/orders

{
  "customerId": "CUST-1001",
  "items": [
    {
      "productId": 3,
      "quantity": 2
    }
  ]
}

Example Response (201 Created)

{
  "orderId": "8a4f6e1d-...",
  "customerId": "CUST-1001",
  "items": [
    {
      "productId": 3,
      "productName": "Wireless Mouse",
      "quantity": 2,
      "unitPrice": 120.00,
      "lineTotal": 240.00
    }
  ],
  "totalPrice": 240.00,
  "orderDate": "2026-06-29T14:30:00",
  "status": "CREATED"
}

Available Endpoints

Method	Endpoint	Description
POST	/api/orders	Create a new order
GET	/api/products	List all products (proxied from Product Service)
GET	/api/products/{id}	Get a product by ID (proxied from Product Service)

🧪 Testing

Run All Tests

./mvnw test

Or in IntelliJ:

• Right-click src/test/java → Run 'All Tests'

Test Coverage

Tests are written for:

• ✅ Controllers — OrderController, ProductController
• ✅ Service Layer — OrderServiceImpl, OrderEventPublisher
• ✅ Mappers — OrderMapper
• ✅ REST Client — ProductCatalogRestClient
• ✅ Exception Handler — GlobalExceptionHandler

View Coverage Report

./mvnw test jacoco:report

Report is generated at target/site/jacoco/index.html.

🔄 CI/CD Pipeline

We use GitHub Actions to automate build and testing on every Pull Request.

Pipeline Steps

1. Checkout source code
2. Set up JDK 21
3. Cache Maven dependencies
4. Run unit tests (mvn test)
5. Build the project (mvn clean package)
6. Run SonarCloud static code analysis
7. Upload test reports as artifacts

Configuration file: .github/workflows/ci.yml

Code Quality

Static code analysis is performed via SonarCloud on every push and pull request. View the project dashboard on SonarCloud for:

• Code coverage
• Bugs and vulnerabilities
• Code smells
• Duplications

🐳 Docker

Verify Data in PostgreSQL

docker exec -it order-postgres psql -U order_user -d order_db -c "SELECT * FROM orders;"

RabbitMQ Management UI

• URL: http://localhost:15672
• Username: guest
• Password: guest

You can view exchanges, queues, bindings, and inspect messages here.

Stop Containers

docker compose down

To also delete the database volume:

docker compose down -v

🌐 Related Services

This microservice is part of a larger system. See the other services:

• Product Service: https://github.com/CSCI44092GroupProject/product-service — manages products, hosted at https://productservice001-cma3gfg4akc3dtgj.centralus-01.azurewebsites.net/swagger-ui/index.html
• Notification Service: https://github.com/CSCI44092GroupProject/notification-service — consumes RabbitMQ events

🤝 Contributing

1. Create a feature branch from main:

git checkout -b feature/your-feature-name

2. Make your changes and commit with a meaningful message:

git commit -m "feat: describe your change"

3. Push the branch and open a Pull Request:

git push origin feature/your-feature-name

4. Wait for the CI pipeline to pass, get code review, then merge.

Commit Message Convention

• feat: — new feature
• fix: — bug fix
• test: — adding or updating tests
• docs: — documentation changes
• refactor: — code refactoring without behavior change
• ci: — CI/CD configuration changes

👥 Team

Name	Student ID	Role
Amindu Bhashana	CS/2020/007	Order Service Developer
Lakith Randula	CS/2020/017	Order Service Developer

📄 License

This project was developed for academic purposes as part of the CSCI 44092 – Software Engineering course.

📚 References

• Spring Boot Documentation
• Spring AMQP (RabbitMQ)
• Springdoc OpenAPI
• Docker Documentation
• GitHub Actions
• SonarCloud