Quick Start

This section provides a step-by-step guide to quickly set up, configure, and run the ClaimProcessingSystem in a development environment.

1. Introduction

The ClaimProcessingSystem is a robust backend application designed to manage and process insurance claims. Built with Spring Boot, it leverages several modern technologies including Apache Kafka for asynchronous messaging and notifications, Redis for caching and session management, Spring Security with JWT for authentication and authorization, and a scheduled batch service for automated claim processing.

2. Prerequisites

Before you begin, ensure you have the following installed on your system:

Java Development Kit (JDK) 17 or higher: The application is built with Java 17.
Apache Maven 3.6.3 or higher: For building and managing project dependencies.
Git: For cloning the repository.
Docker and Docker Compose: Highly recommended for easily setting up required external services (PostgreSQL, Kafka, Redis).
Postman or cURL: For interacting with the application's REST API endpoints.

3. Getting Started

Follow these steps to get the ClaimProcessingSystem up and running:

3.1. Clone the Repository

First, clone the project repository to your local machine:

git clone https://github.com/faizanGeek/ClaimProcessingSystem.git
cd ClaimProcessingSystem

3.2. Build the Project

Navigate to the project root directory and build the application using Maven. This will download all necessary dependencies and compile the code.

mvn clean install

4. External Services Setup (Docker Compose)

The application relies on several external services: a PostgreSQL database, Apache Kafka, and Redis. Using Docker Compose is the quickest way to get these services running for a development environment.

Create a docker-compose.yml file in the root of your ClaimProcessingSystem project with the following content:

version: '3.8'
services:
  db:
    image: postgres:13
    environment:
      POSTGRES_DB: claim_db
      POSTGRES_USER: user
      POSTGRES_PASSWORD: password
    ports:
      - "5432:5432"
    volumes:
      - postgres_data:/var/lib/postgresql/data
  
  redis:
    image: redis:6.2-alpine
    ports:
      - "6379:6379"
    command: redis-server --appendonly yes
    volumes:
      - redis_data:/data

  zookeeper:
    image: confluentinc/cp-zookeeper:7.0.1
    hostname: zookeeper
    ports:
      - "2181:2181"
    environment:
      ZOOKEEPER_CLIENT_PORT: 2181
      ZOOKEEPER_TICK_TIME: 2000

  kafka:
    image: confluentinc/cp-kafka:7.0.1
    hostname: kafka
    ports:
      - "9092:9092"
    depends_on:
      - zookeeper
    environment:
      KAFKA_BROKER_ID: 1
      KAFKA_ZOOKEEPER_CONNECT: 'zookeeper:2181'
      KAFKA_LISTENER_SECURITY_PROTOCOL_MAP: PLAINTEXT:PLAINTEXT,PLAINTEXT_HOST:PLAINTEXT
      KAFKA_ADVERTISED_LISTENERS: PLAINTEXT://kafka:29092,PLAINTEXT_HOST://localhost:9092
      KAFKA_OFFSETS_TOPIC_REPLICATION_FACTOR: 1
      KAFKA_TRANSACTION_STATE_LOG_REPLICATION_FACTOR: 1
      KAFKA_TRANSACTION_STATE_LOG_MIN_ISR: 1
      KAFKA_AUTO_CREATE_TOPICS_ENABLE: "true" # Enables automatic topic creation for quick setup

volumes:
  postgres_data:
  redis_data:

Start the services:

Navigate to the directory where your docker-compose.yml file is located and run:
```
docker-compose up -d
```
This command will download the necessary Docker images and start PostgreSQL, Redis, Zookeeper, and Kafka in detached mode.

5. Application Configuration

The application uses application.properties (or application.yml) for configuration. For a quick start, ensure your src/main/resources/application.properties includes the following settings to connect to the Dockerized services:

# Server Port (default Spring Boot port)
server.port=8080

# Database Configuration (PostgreSQL example)
spring.datasource.url=jdbc:postgresql://localhost:5432/claim_db
spring.datasource.username=user
spring.datasource.password=password
spring.datasource.driver-class-name=org.postgresql.Driver
spring.jpa.hibernate.ddl-auto=update # Use 'create' or 'create-drop' for initial schema generation
spring.jpa.properties.hibernate.dialect=org.hibernate.dialect.PostgreSQLDialect

# Redis Configuration
spring.redis.host=localhost
spring.redis.port=6379

# Kafka Configuration
spring.kafka.bootstrap-servers=localhost:9092

# Email Configuration (for notifications)
# Uncomment and configure if you want to test email notifications.
# For development, you might use a service like Mailtrap.io or a local SMTP server.
# spring.mail.host=smtp.example.com
# spring.mail.port=587
# spring.mail.username=your-email@example.com
# spring.mail.password=your-email-password
# spring.mail.properties.mail.smtp.auth=true
# spring.mail.properties.mail.smtp.starttls.enable=true
# spring.mail.properties.mail.smtp.connectiontimeout=5000
# spring.mail.properties.mail.smtp.timeout=5000
# spring.mail.properties.mail.smtp.writetimeout=5000

6. Running the Application

Once the external services are running and your application.properties is configured, you can run the Spring Boot application:

java -jar target/ClaimProcessingSystem-0.0.1-SNAPSHOT.jar # Adjust '0.0.1-SNAPSHOT' to your project's version

Alternatively, if you are using an IDE (e.g., IntelliJ IDEA, Eclipse), you can run the ProcessingApplication.java class directly.

You should observe Spring Boot logs indicating the application is starting, initializing its components, and successfully connecting to Kafka, Redis, and the database.

7. Initial Usage and Verification

Once the application is running, you can interact with its REST API, typically available at http://localhost:8080. The system uses JWT-based authentication, so you'll need to register and log in to obtain a token for protected endpoints.

7.1. Register a New User

Send a POST request to the /register endpoint to create a new user:

POST http://localhost:8080/register
Content-Type: application/json

{
    "username": "alice.smith",
    "passwordHash": "MySecurePassword123",
    "email": "alice.smith@example.com",
    "role": "USER"
}

7.2. Log In and Obtain JWT

After registration, send a POST request to the /login endpoint. The response will include a JWT token, which you need for subsequent authenticated requests.

POST http://localhost:8080/login
Content-Type: application/json

{
    "username": "alice.smith",
    "password": "MySecurePassword123"
}

Expected Response (example, actual might vary slightly):

{
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJhbGljZS5zbWl0aCIsImlzcyI6IkNsYWltUHJvY2Vzc2luZ1N5c3RlbSJ...",
    "userId": 1,
    "username": "alice.smith",
    "email": "alice.smith@example.com",
    "role": "USER"
}

Copy the token value from the response.

7.3. Submit a Claim (Authenticated)

Use the JWT token obtained from the login step in the Authorization header as a Bearer token.

POST http://localhost:8080/claims
Content-Type: application/json
Authorization: Bearer YOUR_JWT_TOKEN_HERE

{
    "userId": 1, 
    "claimAmount": 150.75,
    "claimType": "Dental"
}

Note: The userId in the claim payload should correspond to the userId obtained during login (e.g., 1 for Alice Smith).

7.4. Observe System Behavior

After submitting a claim:

The claim will initially be recorded with a "Submitted" status.
The system includes a scheduled batch service (ClaimBatchService) that runs hourly to automatically process pending claims (e.g., updating their status from "Pending" to "Processed").
When a claim's status is updated, a message is published to Kafka. A Kafka consumer (configured in KafkaConsumerConfig) listens for these updates and, if email settings are provided, attempts to send an email notification to the user.
You can monitor the application logs for messages related to Kafka operations and claim processing.

You are now ready to explore the full capabilities of the ClaimProcessingSystem!