Todo List Application

A comprehensive Spring Boot REST API for managing todo items with complete history tracking.

Features

• CRUD Operations: Create, read, update, and delete todo items
• Status Management: Track todo items with three states: TODO, STARTED, DONE
• History Tracking: Automatically track all changes made to todo items
• Validation: Built-in validation for required fields and data constraints
• API Documentation: Interactive Swagger UI for testing and documentation
• In-Memory Database: Uses H2 for fast, lightweight data storage
• Sample Data: Pre-loaded with example todo items for testing

Technology Stack

• Java 21: Modern Java features and best practices
• Spring Boot 3.2.0: Latest Spring Boot framework
• Spring Data JPA: Database access and ORM
• H2 Database: In-memory database
• Lombok: Reduce boilerplate code
• Swagger/OpenAPI: API documentation
• JUnit 5 & Mockito: Comprehensive testing
• Gradle: Build automation

Architecture

The application follows Domain-Driven Design (DDD) principles with a layered architecture:

• Domain Layer: Core business entities and repository interfaces
• Application Layer: Service layer with business logic, DTOs, and mappers
• Presentation Layer: REST controllers
• Infrastructure Layer: Configuration, exception handling, and data initialization

Project Structure

src/
├── main/
│   ├── java/com/example/todolist/
│   │   ├── domain/
│   │   │   ├── model/              # Entities
│   │   │   └── repository/          # Repository interfaces
│   │   ├── application/
│   │   │   ├── dto/                 # Data Transfer Objects
│   │   │   ├── mapper/              # Entity-DTO mappers
│   │   │   └── service/             # Business logic
│   │   ├── presentation/
│   │   │   └── controller/          # REST controllers
│   │   └── infrastructure/
│   │       ├── config/              # Configuration classes
│   │       └── exception/           # Exception handling
│   └── resources/
│       └── application.yml          # Application configuration
└── test/
    └── java/com/example/todolist/
        ├── application/service/     # Unit tests
        └── presentation/controller/ # Integration tests

Getting Started

Prerequisites

• Java 21 or higher
• Gradle (or use the included Gradle wrapper)

Running the Application

1. Clone the repository
2. Navigate to the project directory
3. Run the application using Gradle:

./gradlew bootRun

Or on Windows:

gradlew.bat bootRun

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

Running Tests

Execute all tests:

./gradlew test

Building the Application

Create an executable JAR:

./gradlew build

The JAR file will be created in build/libs/

API Endpoints

Todo Items

Method	Endpoint	Description
POST	/api/v1/todos	Create a new todo item
GET	/api/v1/todos	Get all todo items
GET	/api/v1/todos?status={status}	Get todo items by status
GET	/api/v1/todos/{id}	Get a specific todo item
PUT	/api/v1/todos/{id}	Update a todo item
DELETE	/api/v1/todos/{id}	Delete a todo item
GET	/api/v1/todos/{id}/history	Get change history for a todo item

API Documentation

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

H2 Database Console

Access the H2 console at: http://localhost:8080/h2-console

• JDBC URL: jdbc:h2:mem:tododb
• Username: sa
• Password: (leave empty)

Example Usage

Create a Todo Item

curl -X POST http://localhost:8080/api/v1/todos \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Complete project documentation",
    "description": "Write comprehensive documentation for the API",
    "status": "TODO"
  }'

Get All Todo Items

curl http://localhost:8080/api/v1/todos

Update a Todo Item

curl -X PUT http://localhost:8080/api/v1/todos/1 \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Complete project documentation",
    "description": "Write comprehensive documentation for the API",
    "status": "STARTED"
  }'

Get Todo Item History

curl http://localhost:8080/api/v1/todos/1/history

Data Model

TodoItem

• id: Unique identifier
• title: Title of the todo item (required, max 255 characters)
• description: Detailed description (optional, max 1000 characters)
• status: Current status (TODO, STARTED, or DONE)
• createdAt: Creation timestamp
• updatedAt: Last update timestamp
• history: List of all changes made to the item

TodoHistory

• id: Unique identifier
• changeDescription: Description of what changed
• changedAt: Timestamp of the change

Design Patterns Used

• Repository Pattern: Data access abstraction
• Service Layer Pattern: Business logic separation
• DTO Pattern: Data transfer and validation
• Mapper Pattern: Entity-DTO conversion
• Builder Pattern: Object construction (via Lombok)
• Dependency Injection: Loose coupling

Testing

The application includes:

• Unit Tests: Service layer tested with Mockito
• Integration Tests: Full API testing with MockMvc
• Test Coverage: Comprehensive test coverage for business logic and API endpoints

Transaction Management

The service layer uses Spring's @Transactional annotation to ensure:

• Atomic operations
• Data consistency
• Proper rollback on errors
• Read-only optimization for query operations

Validation

Input validation is enforced at the API level using Jakarta Bean Validation:

• Title is required and cannot be empty
• Title cannot exceed 255 characters
• Description cannot exceed 1000 characters
• Status must be a valid enum value

Error Handling

Global exception handling provides consistent error responses:

• 400 Bad Request: Validation errors
• 404 Not Found: Resource not found
• 500 Internal Server Error: Unexpected errors

Sample Data

The application is pre-loaded with 6 sample todo items demonstrating different statuses and history entries.