project statement (phase 1 and 2): link +

project statement (phase 3): link +

Simple Notification Service

This project is a comprehensive, standalone notification service built with Spring Boot. It features a robust, persistent architecture for sending and scheduling notifications, including advanced database querying and geospatial capabilities. The entire development environment is managed through Docker and a convenient Makefile for easy command execution.

---

Features

• RESTful API: Clean, separated endpoints for sending notifications, managing recipients, and querying data.
• Persistent Scheduling: Uses a database-backed TaskScheduler to ensure scheduled notifications are not lost if the application restarts.
• Advanced Querying: Demonstrates multiple query strategies including method-name queries, HQL, native SQL, and the JPA Criteria API.
• Geospatial Capabilities: Utilizes PostGIS to store recipient locations and send notifications to a geographic area.
• Interactive API Documentation: Integrated Swagger UI (OpenAPI 3) for easy API exploration and testing.
• Containerized Database: Uses Docker to run a consistent PostgreSQL + PostGIS database environment.
• Type-Safe Configuration: Centralizes application configuration in a type-safe class, reading values from application.yml.
• Secure Credential Management: Uses a .env file to keep secrets out of version control.

---

Tech Stack

• Backend: Java 21, Spring Boot 3.3.2, Spring Data JPA, Hibernate
• Database: PostgreSQL + PostGIS
• API Documentation: SpringDoc OpenAPI (Swagger UI)
• Containerization: Docker, Docker Compose
• Build & Automation: Maven, Make

---

1. Initial Setup

Prerequisites

• Docker and Docker Compose: Required to run the database.
• Java 21 & Maven 3.6+: Required for local application development.
• Make: Required to use the simplified commands in the Makefile. (On Windows, you can get this through Chocolatey by running choco install make).

Configuration

Before running the application, you must create a configuration file.

1. In the project's root directory, create a new file named .env.
2. Copy the content from the .env.example file and paste it into your new .env file.
3. Modify the values in .env as needed.

.env.example

# --- Application Ports ---
# The port your Spring Boot application will run on
SERVER_PORT=8080
# The port for the PostgreSQL database
DB_PORT=5432

# --- Database Credentials ---
DB_USER=admin
DB_PASSWORD=password
DB_NAME=notification_service

# --- Default Recipient IDs for System Messages ---
# These UUIDs must exist in the database for startup/recurring messages to work.
# You can get these IDs after creating recipients via the API or from the seed script.
RECIPIENT_ID_SCHEDULED="a1b2c3d4-e5f6-7890-1234-567890abcdef"
RECIPIENT_ID_STARTUP="a1b2c3d4-e5f6-7890-1234-567890abcdef"

---

2. How to Run

This project supports two primary workflows, both managed via the Makefile.

Workflow A: Local Development (Recommended)

Run the database in Docker and the Spring Boot application locally from your IDE. This is the fastest way to develop and see code changes instantly.

Step 1: Start the Database Open a terminal in the project root and run:

Bash

make local-up

This starts the PostgreSQL container in the background.

Step 2: Run the Spring Application Open the project in IntelliJ IDEA and run the NotificationServiceApplication.java main method. The application will start and connect to the database running in Docker.

Workflow B: Full Production-Like Build

Build the application into a Docker image and run the entire stack (app + database) inside Docker.

Step 1: Build and Start All Containers

Bash

make prod-up

This command will build the app image and start all services defined in docker-compose.prod.yml.

---

3. Makefile Commands

All common tasks are automated with make. Run these commands from the project's root directory.

Docker Environment

Command	Description
make local-up	Starts the PostgreSQL database container for local development.
make local-down	Stops the local database container.
make prod-up	Builds the app image and starts the full production environment.
make prod-down	Stops the full production environment.
make logs	Opens Lazydocker, a friendly UI for viewing container logs and status.

Database Management (Destructive ☢️)

Command	Description
make db-clean	Stops the containers and deletes all database data files (the volume).
make db-reset	Wipes and re-initializes the database while it is running.
make db-truncate	Empties the notifications and recipients tables without a full reset.
make db-seed	Clears the tables and populates the database with sample data from db-seed/seed.sql.

Maven Build

Command	Description
make clean	Cleans the Maven target directory.
make package	Packages the application into a runnable JAR.
make build	Runs both clean and package together.

Export to Sheets

---

4. API Documentation (Swagger UI)

Once the application is running, you can access the interactive API documentation to explore and test all available endpoints.

• URL: http://localhost:8080/api/swagger-ui.html

The UI provides a complete description of all endpoints, DTO schemas (with examples), and allows you to send live requests to the application.

---

We would like to express our sincere gratitude to all the Hammasir Bootcamp mentors for their invaluable guidance, encouragement, and expertise throughout this journey. Your dedication and support have been instrumental in helping us deepen our understanding of backend development and Spring Boot, and we truly appreciate the time and effort you invested in our growth.