GraphQL CRUD API - Employee Management System

A comprehensive Employee Management System built with Spring Boot and GraphQL, featuring complete CRUD operations, address management, configurable timezone support, and robust data validation.

Features

• Complete CRUD Operations: Create, Read, Update, Delete employees with comprehensive validation
• Address Management: Full address support with employee relationships and orphan removal
• GraphQL API: Modern API with queries and mutations, custom DateTime scalar handling
• Configurable Timezone: Support for different timezones via environment configuration
• PostgreSQL Integration: Robust database support with JPA/Hibernate and optimized queries
• Environment Profiles: Different configurations for dev/prod/local environments with YAML configuration
• Advanced Validation: Jakarta Bean Validation with custom constraints and error handling
• Performance Optimization: N+1 query prevention with JOIN FETCH, database indexing, and paginated queries

Tech Stack

Backend Framework

• Java 21 - Modern language features with toolchain configuration
• Spring Boot 3.5.5 - Main framework with auto-configuration
• Spring GraphQL - GraphQL integration with Spring ecosystem
• Spring Data JPA - Data access layer with Hibernate implementation

Database & Persistence

• PostgreSQL - Production database with ACID compliance
• Hibernate 6.x - ORM with advanced query optimization
• Database Indexing - Performance optimization on frequently queried columns
• Connection Pooling - Efficient database connection management

Development Tools & Libraries

• Lombok 1.18.38 - Boilerplate code reduction with @SuperBuilder pattern
• Gradle 8.x - Build system with dependency management
• Jakarta Validation - Bean validation with custom annotations
• Spring Boot DevTools - Development-time features for faster iteration

GraphQL Features

• Custom DateTime Scalar - Configurable date/time formatting with timezone support
• Schema-First Design - Separate types for queries vs mutations (Employee vs EmployeeData)
• GraphiQL Integration - Interactive query explorer for development
• Exception Handling - Global GraphQL error handling with detailed messages

Architecture & Patterns

• Record Classes - Immutable DTOs for type safety
• Custom Mappers - Entity/DTO mapping with Spring bean configuration
• Service Layer Pattern - Clean separation of concerns
• Repository Pattern - Data access abstraction with custom queries
• Configuration Properties - Environment-specific settings via @ConfigurationProperties Employee Management System

A Spring Boot application that provides a complete GraphQL API for managing employees and their addresses with configurable timezone and date formatting support.

Features

• Complete CRUD Operations: Create, Read, Update, Delete employees
• Address Management: Full address support with employee relationships
• GraphQL API: Modern API with queries, mutations, and subscriptions
• Configurable Timezone: Support for different timezones via configuration
• PostgreSQL Integration: Robust database support with JPA/Hibernate
• Environment Profiles: Different configurations for dev/prod/local environments

Quick Start

Prerequisites

• Java 21+
• PostgreSQL running on localhost:5432
• Database named employee_db

Running the Application

# Development (UTC timezone)
./gradlew bootRun --args='--spring.profiles.active=dev'

# Local development (Asia/Dhaka timezone)
./gradlew bootRun --args='--spring.profiles.active=local'

# Production
./gradlew bootRun --args='--spring.profiles.active=prod'

Environment Configuration

Set these environment variables for custom configuration:

export APP_TIMEZONE="UTC"
export APP_DATE_FORMAT="yyyy-MM-dd HH:mm:ss"

API Endpoints

• GraphQL: http://localhost:9491/graphql
• GraphiQL: http://localhost:9491/graphiql (development only)

Sample GraphQL Operations

Create Employee

mutation {
  createEmployee(input: {
    firstName: "John"
    lastName: "Doe"
    email: "john.doe@example.com"
    role: "Software Engineer"
    address: {
      street: "123 Main St"
      city: "New York"
      state: "NY"
      zipCode: "10001"
    }
  }) {
    id
    firstName
    lastName
    email
    role
    address {
      street
      city
      state
      zipCode
    }
  }
}

Get All Employees

query {
  getAllEmployees {
    id
    firstName
    lastName
    email
    role
    address {
      street
      city
      state
      zipCode
    }
    createdAt
  }
}

Update Employee

mutation {
  updateEmployee(id: 1, input: {
    role: "Senior Software Engineer"
  }) {
    id
    firstName
    lastName
    role
  }
}

Configuration Files

• application.yaml - Main configuration
• application-dev.yaml - Development environment (UTC)
• application-prod.yaml - Production environment (UTC, ISO format)
• application-local.yaml - Local development (Asia/Dhaka)

Testing

Unit & Integration Tests

./gradlew test

Postman Collection

Import GraphQL_Employee_API.postman_collection.json into Postman for comprehensive API testing with:

• Pre-configured queries and mutations
• Environment variables setup
• Validation examples
• Error handling scenarios

cURL Testing

# Quick test
curl -X POST http://localhost:9491/graphql \
  -H 'Content-Type: application/json' \
  -d '{"query": "query { getAllEmployees { id firstName lastName } }"}'

Additional Testing Resources

• Quick_cURL_Reference.md - Command-line testing examples
• Custom_API_Response_Examples.md - API response format documentation
• GraphQL_API_Testing_Collection.md - Comprehensive testing guide

Docker Support

version: '3.8'
services:
  app:
    image: graphql-crud:latest
    environment:
      - APP_TIMEZONE=UTC
      - APP_DATE_FORMAT=yyyy-MM-dd HH:mm:ss
      - SPRING_PROFILES_ACTIVE=prod
    ports:
      - "9491:9491"

Development

Project Structure

src/
├── main/java/com/graphql/
│   ├── config/          # Configuration classes
│   ├── controller/      # GraphQL controllers
│   ├── dto/            # Data transfer objects
│   ├── entity/         # JPA entities
│   ├── repository/     # Data repositories
│   └── service/        # Business logic
└── main/resources/
    ├── graphql/        # GraphQL schema
    └── application*.yaml

Database Configuration

Database Setup

CREATE DATABASE employee_db;
-- Tables are auto-created via Hibernate DDL

Connection Properties

spring:
  datasource:
    url: jdbc:postgresql://localhost:5432/employee_db
    username: postgres
    password: root
    driver-class-name: org.postgresql.Driver
  jpa:
    hibernate:
      ddl-auto: update
    properties:
      hibernate:
        dialect: org.hibernate.dialect.PostgreSQLDialect

Performance Features

• Optimized Queries: JOIN FETCH to prevent N+1 problems
• Database Indexing: Indexes on email, name fields for faster lookups
• Paginated Queries: Large dataset handling with Spring Data Pageable
• Connection Pooling: HikariCP for efficient connection management

Key Components

• GraphQLConfig: Custom DateTime scalar with timezone-aware formatting
• ApplicationProperties: Environment-based configuration with @ConfigurationProperties
• BaseEntity: Audit timestamps with @CreationTimestamp and @UpdateTimestamp
• EmployeeController: GraphQL @QueryMapping and @MutationMapping handlers
• EmployeeMapper: Custom entity/DTO mapping with validation logic
• Global Exception Handler: Comprehensive GraphQL error handling with detailed messages
• Custom Validation: Jakarta Bean Validation with domain-specific constraints

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

License

This project is licensed under the MIT License.