Store Finder

Store Finder is a service that manages and provides detailed information about Jumbo stores, including operating hours, geolocation, address, collection point status, and location type. It also supports geospatial queries to identify stores near a specific coordinate within a defined radius.

🌟 Core Features

• Find the top N nearby stores based on:
  • Input longitude, latitude
  • Optional radius (e.g., 800m, 10km)
  • Optional size (default - 5)
• Retrieve a list of stores with optional filters by:
  • city
  • collectionPoint
  • storeLocationType
  • openNow
• Add, update, or delete store records (secured via JWT-based authentication)
• Fetch lists of:
  • Store information
  • Available cities
  • Store location types
• 🛠️ Developer Tooling
  • Swagger UI – Interactive API documentation
  • Liquibase – Versioned database migrations
  • Heroku – Live deployment
  • GitHub Actions – Automated CI/CD pipeline
  • Postman collection - stores-api.postman_collection.json
  • Google checkstyle incorporated - ./mvnw clean checkstyle:checkstyle

Techstack used👾

• Java 21
• Spring Boot 3
• Maven 3.9
• Docker
• docker-compose
• Github Actions
• Liquibase
• MapStruct
• Postgres with Postgis
• Redis
• JWT
• Jasypt
• Junit 5
• TestContainers
• Heroku
• swagger
• postman
• google checkstyle

🚀 How to Run the Project

🔧 Prerequisites

Ensure the following tools are installed:

• Java 21
• Apache Maven 3.9
• Docker
• Docker Compose
• Jasypt CLI Tool (Only required if modifying encrypted properties)

---

📁 Environment Variable Setup

The application relies on environment variables for configuration. You can set them in a .env file at the project root.

📝 Example .env file

export SPRING_DATASOURCE_DATABASE=storeapi
export SPRING_DATASOURCE_URL=jdbc:postgresql://postgis:5432/${SPRING_DATASOURCE_DATABASE}
export SPRING_DATASOURCE_USERNAME=user
export SPRING_DATASOURCE_PASSWORD=password

export JASYPT_ENCRYPTOR_PASSWORD=jasypt-encrypt-passwd

export SPRING_REDIS_HOST=redis
export SPRING_REDIS_PORT=6379

⚠️ Make sure to keep sensitive keys (like JASYPT_ENCRYPTOR_PASSWORD) secure and private. Never commit them to version control.

---

📦 Setup and Run

This application is Dockerized using docker-compose.yml, bundling the backend, Postgres, and Redis.

1. Clone the repository

git clone [email protected]:ImShakthi/Store-Finder.git
cd Store-Finder

2. Build the application using Maven

./mvnw clean package

3. Build and start the server with Docker Compose, export all environment variables

docker-compose --env-file=.env up --build

4. Access Swagger UI to explore available APIs:

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

---

⚙️ CI/CD

CI/CD is handled via GitHub Actions and Heroku.

• CI/CD Pipeline = GitHub Actions

• Live Deployment (Heroku) https://jumbo-store-api-f1ae1b3de689.herokuapp.com/swagger-ui/index.html

📝 Note: The Heroku server is hosted on a free-tier plan. Expect some delay due to cold starts when inactive.*

🧪 How to Test the Store-Finder Service

Store-Finder supports both unit tests and integration tests. Integration testing is designed to simulate real-world usage, and includes full journey validation for core features like store management, store details, and authentication.

The integration test class com.skthvl.storeapi.StoreApiApplicationTests demonstrates a complete user journey.

---

✅ Run All Tests

./mvnw clean test

🧱 Integration Testing Stack

• ✅ Testcontainers – Spins up isolated Postgres and Redis containers during integration tests

These tools ensure tests are environment-independent and do not rely on external services or shared databases.

🚀 Run the Server Locally

To run the app locally, build the project and start the services using Docker Compose:

./mvnw clean package

docker-compose --env-file=.env up --build

⚠️Note: create .env file if not exist and never commit it to repository.

📬 Test the API

You can test the REST APIs via:

• Swagger UI: http://localhost:8080/swagger-ui/index.html
• Postman Collection: Import from the file: stores-api.postman_collection.json