Docs improvements

README.md

@@ -1,49 +1,111 @@
+[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE.txt)
+
 # Backend Core
 
-Commons utilities for backend enterprise application development
+Common utilities for backend enterprise application development.
 
-## What is backend-core?
+Backend Core provides a set of modular libraries to help you implement clean architecture (three-tier, hexagonal, DDD) in your enterprise Java applications. It includes:
 
-It's a set of common interfaces and implementations that allows to implement some of the principles of a clean architectural design for enterprise applications.
+- **Model layer**: domain interfaces and DTOs (`backend-core-model`)
+- **Data layer**: persistence contracts (`backend-core-data`) and JPA-based implementations (`backend-core-data-impl`)
+- **Service layer**: business logic contracts (`backend-core-business`) and default implementations (`backend-core-business-impl`)
+- **Spring Boot integration**: auto-configuration support (`backend-core-business-spring-impl`)
 
-For more info, please refer to [Documentation](src/site/markdown/index.md)
+## Features
 
-Snapshots are available [here](https://maven.flowingcode.com/snapshots). 
+- Generic CRUD interfaces and base implementations
+- Strongly-typed filtering and query support
+- Reusable service layering and transactional support
+- Spring Boot integration for easy wiring
+- Fully documented design and examples
 
-## Download release
+## Getting Started
 
-Comming soon
+### Prerequisites
 
-## Building
+- Java 17 or higher
+- Maven 3.x
 
-- git clone repository
-- mvn clean install
+### Build from Source
 
-## Release notes
+```bash
+git clone https://github.com/FlowingCode/backend-core.git
+cd backend-core
+mvn clean install
+```
 
-See [here](https://github.com/FlowingCode/backend-core/releases)
+### Generate Documentation
 
-## Issue tracking
+```bash
+mvn site
+# Open target/site/index.html in your browser
+```
 
-Issues for this project are tracked [here](https://github.com/FlowingCode/backend-core/issues). All bug reports and feature requests are appreciated. 
+## Usage
 
-## Contributions
+### Available Modules
 
-Contributions are welcome, but there are no guarantees that they are accepted as such. Process for contributing is the following:
+| Module                             | Description                                                          |
+|------------------------------------|----------------------------------------------------------------------|
+| `backend-core-model`               | Domain interfaces, DTOs, exceptions and validation                   |
+| `backend-core-data`                | DAO contracts (CRUD, Query, etc.)                                    |
+| `backend-core-data-impl`           | JPA implementations for DAO contracts                                |
+| `backend-core-business`            | Service contracts (business logic interfaces)                        |
+| `backend-core-business-impl`       | Default implementations for business/service contracts               |
+| `backend-core-business-spring-impl`| Spring Boot auto-configuration for services and repositories          |
 
-- Fork this project
-- Create an issue to this project about the contribution (bug or feature) if there is no such issue about it already. Try to keep the scope minimal.
-- Develop and test the fix or functionality carefully. Only include minimum amount of code needed to fix the issue.
-- Refer to the fixed issue in commit
-- Send a pull request for the original project
-- Comment on the original issue that you have implemented a fix for it
+Add the desired module(s) to your project's dependencies:
 
-## License & Author
+```xml
+<!-- Replace <artifactId> with the module(s) you need -->
+<dependency>
+  <groupId>com.flowingcode.backend-core</groupId>
+  <artifactId>backend-core-data</artifactId>
+  <version>1.1.0-SNAPSHOT</version>
+</dependency>
+```
+
+Snapshots are available at:
+
+```xml
+<repository>
+  <id>flowingcode-snapshots</id>
+  <url>https://maven.flowingcode.com/snapshots</url>
+  <snapshots>
+    <enabled>true</enabled>
+  </snapshots>
+</repository>
+```
+
+For release versions, see Maven Central (coming soon).
+
+## Documentation
+
+Detailed design documentation and API reference are available via the Maven Site and in the source Markdown docs:
+
+- [Maven Site](target/site/index.html)
+- [Design documentation](src/site/markdown/index.md)
 
-Commons-Backend is distributed under Apache License 2.0. For license terms, see LICENSE.txt.
+## Release Notes
 
-Commons-Backend is written by Flowing Code
+See the [GitHub releases](https://github.com/FlowingCode/backend-core/releases).
+
+## Issue Tracking
+
+Report bugs and request features on [GitHub Issues](https://github.com/FlowingCode/backend-core/issues).
+
+## Contributing
+
+Contributions are welcome! Please follow the process outlined below:
+
+1. Fork this repository.
+2. Create an issue for your contribution (bug or feature request), or select an existing one.
+3. Develop and test your changes carefully; include only the minimum code required.
+4. Reference the issue in your commit messages.
+5. Send a pull request and comment on the issue once it's ready.
+
+## License & Author
 
-# Developer Guide
+This library is distributed under Apache License 2.0. For license terms, see LICENSE.txt.
 
-Comming soon
+Backend Core is written by Flowing Code S.A.

backend-core-business-impl/src/main/java/com/flowingcode/backendcore/service/validation/CreationValidator.java

@@ -28,6 +28,12 @@
 import com.flowingcode.backendcore.model.ErrorDescription;
 import com.flowingcode.backendcore.validation.Validator;
 
+/**
+ * Validator for creation operations on entities.
+ *
+ * @param <T> the type being validated
+ * @author mlopez
+ */
 public interface CreationValidator<T> extends Validator<T> {
 
   default CreationValidator<T> and(CreationValidator<T> then) {

backend-core-business-impl/src/main/java/com/flowingcode/backendcore/service/validation/DeletionValidator.java

@@ -28,6 +28,12 @@
 import com.flowingcode.backendcore.model.ErrorDescription;
 import com.flowingcode.backendcore.validation.Validator;
 
+/**
+ * Validator for deletion operations on entities.
+ *
+ * @param <T> the type being validated
+ * @author mlopez
+ */
 public interface DeletionValidator<T> extends Validator<T> {
 
   default DeletionValidator<T> and(DeletionValidator<T> then) {

backend-core-business-impl/src/main/java/com/flowingcode/backendcore/service/validation/InvariantValidator.java

@@ -10,6 +10,12 @@
 import com.flowingcode.backendcore.service.validation.UpdateValidator;
 import com.flowingcode.backendcore.validation.Validator;
 
+/**
+ * Validator that enforces invariants during both creation and update operations.
+ *
+ * @param <T> the type being validated
+ * @author jgodoy
+ */
 public interface InvariantValidator<T> extends CreationValidator<T>, UpdateValidator<T> {
 
   default InvariantValidator<T> and(InvariantValidator<T> then) {

backend-core-business-impl/src/main/java/com/flowingcode/backendcore/service/validation/ServiceValidationKind.java

@@ -6,6 +6,11 @@
 import lombok.Getter;
 import lombok.RequiredArgsConstructor;
 
+/**
+ * Enumeration of service validation kinds corresponding to different operation types.
+ *
+ * @author mlopez
+ */
 @RequiredArgsConstructor
 public enum ServiceValidationKind implements ValidationKind {
 

backend-core-business-impl/src/main/java/com/flowingcode/backendcore/service/validation/UpdateValidator.java

@@ -28,6 +28,12 @@
 import com.flowingcode.backendcore.model.ErrorDescription;
 import com.flowingcode.backendcore.validation.Validator;
 
+/**
+ * Validator for update operations on entities.
+ *
+ * @param <T> the type being validated
+ * @author mlopez
+ */
 public interface UpdateValidator<T> extends Validator<T> {
 
   default UpdateValidator<T> and(UpdateValidator<T> then) {

backend-core-business-spring-impl/src/main/java/com/flowingcode/backendcore/service/ConstraintSpecification.java

@@ -13,6 +13,13 @@
 import lombok.AccessLevel;
 import lombok.RequiredArgsConstructor;
 
+/**
+ * Spring Data JPA {@code Specification} that applies a model
+ * {@code Constraint}.
+ *
+ * @param <T> the entity type
+ * @author jgodoy
+ */
 @SuppressWarnings("serial")
 @RequiredArgsConstructor(access = AccessLevel.PRIVATE)
 final class ConstraintSpecification<T> implements Specification<T> {

backend-core-data-impl/src/main/java/com/flowingcode/backendcore/dao/jpa/ConstraintTransformerJpaImpl.java

@@ -44,6 +44,12 @@
 import lombok.NonNull;
 import lombok.RequiredArgsConstructor;
 
+/**
+ * JPA implementation of {@code ConstraintTransformer} for converting
+ * model constraints into JPA {@code Predicate} instances.
+ *
+ * @author jgodoy
+ */
 @RequiredArgsConstructor
 public class ConstraintTransformerJpaImpl extends ConstraintTransformer<Predicate> {
 

backend-core-data-impl/src/main/java/com/flowingcode/backendcore/dao/jpa/ConversionJpaDaoSupport.java

@@ -39,6 +39,14 @@
 import com.flowingcode.backendcore.model.Identifiable;
 import com.flowingcode.backendcore.model.QuerySpec;
 
+/**
+ * DAO support interface that converts between source domain type S and persistent entity type T and provides generic CRUD operations.
+ *
+ * @param <S> the source domain type
+ * @param <T> the persistent entity type
+ * @param <K> the identifier type
+ * @author mlopez
+ */
 public interface ConversionJpaDaoSupport<S, T extends Identifiable<K>, K extends Serializable>
 		extends CrudDao<S, K> {
 

backend-core-data-impl/src/main/java/com/flowingcode/backendcore/dao/jpa/JpaDaoSupport.java

@@ -23,6 +23,13 @@
 
 import com.flowingcode.backendcore.model.Identifiable;
 
+/**
+ * DAO support interface for JPA entities, providing default identity conversions.
+ *
+ * @param <T> the persistent entity type
+ * @param <K> the identifier type
+ * @author mlopez
+ */
 public interface JpaDaoSupport<T extends Identifiable<K>, K extends Serializable>
 		extends ConversionJpaDaoSupport<T, T, K> {
 

backend-core-data/src/main/java/com/flowingcode/backendcore/dao/CreationDao.java

@@ -19,6 +19,13 @@
  */
 package com.flowingcode.backendcore.dao;
 
+/**
+ * Data access interface for creating entities of type T.
+ *
+ * @param <T> the entity type
+ * @param <K> the identifier type returned upon creation
+ * @author mlopez
+ */
 public interface CreationDao<T, K> {
 
 	K save(T entity);

backend-core-data/src/main/java/com/flowingcode/backendcore/dao/CrudDao.java

@@ -19,7 +19,14 @@
  */
 package com.flowingcode.backendcore.dao;
 
+/**
+ * Generic CRUD data access interface combining create, retrieve, update, and delete operations.
+ *
+ * @param <T> the entity type
+ * @param <K> the identifier type
+ * @author mlopez
+ */
 public interface CrudDao<T, K>
-		extends CreationDao<T, K>, UpdateDao<T>, DeletionDao<T>, QueryDao<T, K> {
+	extends CreationDao<T, K>, UpdateDao<T>, DeletionDao<T>, QueryDao<T, K> {
 
 }

backend-core-data/src/main/java/com/flowingcode/backendcore/dao/DeletionDao.java

@@ -19,6 +19,12 @@
  */
 package com.flowingcode.backendcore.dao;
 
+/**
+ * Data access interface for deleting entities of type T.
+ *
+ * @param <T> the entity type
+ * @author mlopez
+ */
 public interface DeletionDao<T> {
 
 	void delete(T entity);

backend-core-data/src/main/java/com/flowingcode/backendcore/dao/QueryDao.java

@@ -24,6 +24,13 @@
 
 import com.flowingcode.backendcore.model.QuerySpec;
 
+/**
+ * Data access interface for querying entities of type T identified by keys of type K.
+ *
+ * @param <T> the entity type
+ * @param <K> the identifier type
+ * @author mlopez
+ */
 public interface QueryDao<T, K> {
 
 	Optional<T> findById(K id);

backend-core-data/src/main/java/com/flowingcode/backendcore/dao/UpdateDao.java

@@ -19,6 +19,12 @@
  */
 package com.flowingcode.backendcore.dao;
 
+/**
+ * Data access interface for updating entities of type T.
+ *
+ * @param <T> the entity type
+ * @author mlopez
+ */
 public interface UpdateDao<T> {
 
 	void update(T entity);

backend-core-model/src/main/java/com/flowingcode/backendcore/model/Constraint.java

@@ -21,6 +21,11 @@
 
 import com.flowingcode.backendcore.model.constraints.NegatedConstraint;
 
+/**
+ * General constraint interface representing a filtering criterion for queries.
+ *
+ * @author jgodoy
+ */
 public interface Constraint {
 
   default Constraint not() {

backend-core-model/src/main/java/com/flowingcode/backendcore/model/constraints/AttributeBetweenConstraint.java

@@ -26,6 +26,11 @@
 import lombok.NonNull;
 import lombok.experimental.FieldDefaults;
 
+/**
+ * Constraint that checks if an attribute's value falls between two inclusive bounds.
+ *
+ * @author jgodoy
+ */
 @Getter
 @FieldDefaults(level = AccessLevel.PRIVATE, makeFinal = true)
 public class AttributeBetweenConstraint implements AttributeConstraint {

backend-core-model/src/main/java/com/flowingcode/backendcore/model/constraints/AttributeConstraint.java

@@ -21,6 +21,11 @@
 
 import com.flowingcode.backendcore.model.Constraint;
 
+/**
+ * Specialization of {@code Constraint} that applies to entity attributes.
+ *
+ * @author jgodoy
+ */
 public interface AttributeConstraint extends Constraint {
 
 	String getAttribute();

backend-core-model/src/main/java/com/flowingcode/backendcore/model/constraints/AttributeILikeConstraint.java

@@ -25,6 +25,11 @@
 import lombok.RequiredArgsConstructor;
 import lombok.experimental.FieldDefaults;
 
+/**
+ * Constraint that performs case-insensitive pattern matching (ILIKE) on an attribute.
+ *
+ * @author jgodoy
+ */
 @Getter
 @RequiredArgsConstructor
 @FieldDefaults(level = AccessLevel.PRIVATE, makeFinal = true)

backend-core-model/src/main/java/com/flowingcode/backendcore/model/constraints/AttributeInConstraint.java

@@ -27,6 +27,11 @@
 import lombok.RequiredArgsConstructor;
 import lombok.experimental.FieldDefaults;
 
+/**
+ * Constraint that checks if the specified attribute's value is contained within a given collection.
+ *
+ * @author jgodoy
+ */
 @Getter
 @RequiredArgsConstructor
 @FieldDefaults(level = AccessLevel.PRIVATE, makeFinal = true)