CrudX SpringBoot Framework

Zero-Boilerplate CRUD Operations for Spring Boot Applications

CrudX is a lightweight, high-performance framework that eliminates repetitive CRUD code in Spring Boot applications. Write just your entity and controller - CrudX automatically generates services, repositories, and REST APIs for MySQL, PostgreSQL, and MongoDB.

---

🚀 Why CrudX?

The Problem

Traditional Spring Boot CRUD development requires:

• Writing repetitive repository interfaces
• Creating service layer implementations
• Building controller endpoints
• Implementing pagination, sorting, and filtering
• Managing transactions and error handling
• Writing extensive boilerplate code for each entity

Result: 200-300 lines of repetitive code per entity.

The Solution

CrudX reduces this to just 5 steps and eliminates 90% of boilerplate code:

// 1. Enable CrudX
@SpringBootApplication
@CrudX
public class MyApp { }

// 2. Create Entity (extends CrudXMySQLEntity, CrudXPostgreSQLEntity, or CrudXMongoEntity)
public class Employee extends CrudXMySQLEntity<Long> {
    private String name;
    private String email;
}

// 3. Create Controller (extends CrudXController)
@RestController
@RequestMapping("/api/employees")
public class EmployeeController extends CrudXController<Employee, Long> { }

That's it! CrudX auto-generates 15+ REST endpoints with full CRUD functionality.

---

✨ Key Features

🎯 Zero-Boilerplate Architecture

• Auto-Service Generation: Services created automatically at startup
• Auto-Repository Management: No need to write repository interfaces
• Smart Entity Detection: Automatically discovers and registers entities
• Convention over Configuration: Sensible defaults, customize when needed

🗄️ Multi-Database Support

• MySQL - Full support with auto-configuration
• PostgreSQL - Optimized for PostgreSQL features
• MongoDB - NoSQL support with reactive capabilities
• Mix and match databases in the same application

🔥 Production-Ready Features

• Batch Operations: Bulk create/delete with skip-on-duplicate support
• Smart Pagination: Auto-switches to pagination for large datasets (>1000 records)
• Memory Optimization: Cursor-based streaming for large data retrieval
• Unique Constraints: @CrudXUniqueConstraint annotation support
• Audit Trail: Automatic createdAt, updatedAt, createdBy, updatedBy
• Error Handling: Comprehensive exception handling with meaningful messages

📊 Performance Monitoring (Optional)

• Real-time Dashboard: Built-in performance analytics UI
• Request Tracking: Monitor response times, success rates, memory usage
• Endpoint Analytics: Per-endpoint performance metrics
• Memory Profiling: Thread-accurate memory allocation tracking
• Zero Configuration: Enable with crudx.performance.enabled=true

🛡️ Enterprise Features

• Transaction Management: Automatic transaction handling
• Validation Support: Jakarta Bean Validation integration
• Custom Business Logic: Override lifecycle hooks for custom behavior
• RESTful Standards: Follows REST best practices
• CORS Support: Built-in CORS configuration

---

📦 Installation (Upgrading from v1.0.0)

Maven

<dependency>
    <groupId>io.github.sachinnimbal</groupId>
    <artifactId>crudx-starter</artifactId>
    <version>1.0.1</version> <!-- Update version -->
</dependency>

<!-- Add your database driver -->
<dependency>
    <groupId>com.mysql</groupId>
    <artifactId>mysql-connector-j</artifactId>
    <version>8.3.0</version>
    <scope>runtime</scope>
</dependency>

Gradle

implementation 'io.github.sachinnimbal:crudx-starter:1.0.1'

// Add your database driver
runtimeOnly 'com.mysql:mysql-connector-j:8.3.0'

---

🎓 Quick Start (5 Steps)

Step 1: Enable CrudX

@SpringBootApplication
@CrudX
public class MyApplication {
    public static void main(String[] args) {
        SpringApplication.run(MyApplication.class, args);
    }
}

Step 2: Configure Database

MySQL/PostgreSQL (application.yml):

spring:
  datasource:
    url: jdbc:mysql://localhost:3306/mydb
    username: root
    password: password
  jpa:
    hibernate:
      ddl-auto: update

MongoDB (application.yml):

spring:
  data:
    mongodb:
      uri: mongodb://localhost:27017/mydb

Step 3: Create Entity

Choose the base class for your database:

MySQL:

@Entity
public class Employee extends CrudXMySQLEntity<Long> {
    private String name;
    private String email;
    private String department;
    
    // Getters and setters
}

PostgreSQL:

@Entity
public class Employee extends CrudXPostgreSQLEntity<Long> {
    private String name;
    private String email;
    private String department;
}

MongoDB:

@Document
public class Employee extends CrudXMongoEntity<String> {
    private String name;
    private String email;
    private String department;
}

Step 4: Create Controller

@RestController
@RequestMapping("/api/employees")
public class EmployeeController extends CrudXController<Employee, Long> {
    // That's it! 15+ endpoints auto-generated
}

Step 5: Run & Test

curl http://localhost:8080/api/employees

---

🔌 Auto-Generated Endpoints

CrudX automatically creates these REST endpoints:

Method	Endpoint	Description
POST	/api/employees	Create single entity
POST	/api/employees/batch	Batch create with duplicate handling
GET	/api/employees	Get all (auto-paginated if >1000)
GET	/api/employees/paged	Get paginated results
GET	/api/employees/{id}	Get by ID
GET	/api/employees/count	Get total count
GET	/api/employees/exists/{id}	Check existence
PATCH	/api/employees/{id}	Partial update
DELETE	/api/employees/{id}	Delete by ID
DELETE	/api/employees/batch	Batch delete with skip tracking
DELETE	/api/employees/batch/force	Force delete (skip existence check)

Query Parameters:

• page, size - Pagination
• sortBy, sortDirection - Sorting
• skipDuplicates - Batch operations behavior

---

💡 Advanced Features

1. Unique Constraints

@Entity
@CrudXUniqueConstraint(
    fields = {"email"}, 
    message = "Email already exists"
)
@CrudXUniqueConstraint(
    fields = {"name", "department"}, 
    message = "Employee name must be unique within department"
)
public class Employee extends CrudXMySQLEntity<Long> {
    private String name;
    private String email;
    private String department;
}

2. Batch Operations

# Create multiple entities (skip duplicates)
POST /api/employees/batch?skipDuplicates=true
[
  {"name": "crudx", "email": "crudx@example.com"},
  {"name": "crud", "email": "crud@example.com"}
]

# Response includes created and skipped counts
{
  "success": true,
  "data": {
    "createdEntities": [...],
    "skippedCount": 2,
    "skippedReasons": ["Duplicate email: crudx@example.com", ...]
  }
}

3. Smart Pagination

# Auto-switches to pagination for large datasets
GET /api/employees
# Returns first 50 records if total > 1000

# Manual pagination
GET /api/employees/paged?page=0&size=20&sortBy=name&sortDirection=ASC

4. Custom Business Logic

@RestController
@RequestMapping("/api/employees")
public class EmployeeController extends CrudXController<Employee, Long> {
    
    @Override
    protected void beforeCreate(Employee entity) {
        // Custom validation
        entity.setEmail(entity.getEmail().toLowerCase());
    }
    
    @Override
    protected void afterCreate(Employee entity) {
        // Send welcome email
        emailService.sendWelcome(entity.getEmail());
    }
}

Available Lifecycle Hooks:

• beforeCreate() / afterCreate()
• beforeUpdate() / afterUpdate()
• beforeDelete() / afterDelete()
• beforeCreateBatch() / afterCreateBatch()
• beforeDeleteBatch() / afterDeleteBatch()
• afterFindById() / afterFindAll() / afterFindPaged()

5. Performance Monitoring

Enable the built-in dashboard:

crudx:
  performance:
    enabled: true
    dashboard-enabled: true
    dashboard-path: /crudx/performance
    track-memory: true
    max-stored-metrics: 1000
    retention-minutes: 60

Access dashboard at: http://localhost:8080/crudx/performance/dashboard

Dashboard Features:

• Real-time request monitoring
• Response time analytics
• Memory usage tracking
• Success/failure rates
• Per-endpoint statistics
• Top slow endpoints
• Error tracking

---

🎯 Real-World Examples

E-Commerce Application

// Product Management
@Entity
@CrudXUniqueConstraint(fields = {"sku"})
public class Product extends CrudXMySQLEntity<Long> {
    private String name;
    private String sku;
    private BigDecimal price;
    private Integer stock;
}

@RestController
@RequestMapping("/api/products")
public class ProductController extends CrudXController<Product, Long> {
    @Override
    protected void beforeUpdate(Long id, Map<String, Object> updates, Product existing) {
        // Track stock changes
        if (updates.containsKey("stock")) {
            inventoryService.logStockChange(id, existing.getStock(), 
                (Integer) updates.get("stock"));
        }
    }
}

User Management System

@Document
@CrudXUniqueConstraint(fields = {"username"})
@CrudXUniqueConstraint(fields = {"email"})
public class User extends CrudXMongoEntity<String> {
    private String username;
    private String email;
    private String passwordHash;
    private Set<String> roles;
}

@RestController
@RequestMapping("/api/users")
public class UserController extends CrudXController<User, String> {
    @Autowired
    private PasswordEncoder passwordEncoder;
    
    @Override
    protected void beforeCreate(User user) {
        user.setPasswordHash(passwordEncoder.encode(user.getPasswordHash()));
        user.setRoles(Set.of("USER"));
    }
}

Multi-Database Application

// MySQL for transactional data
@Entity
public class Order extends CrudXMySQLEntity<Long> {
    private Long customerId;
    private BigDecimal totalAmount;
}

// MongoDB for flexible documents
@Document
public class CustomerProfile extends CrudXMongoEntity<String> {
    private String customerId;
    private Map<String, Object> preferences;
    private List<String> tags;
}

---

📊 Performance Benchmarks

Operation	Traditional Spring Boot	CrudX
Code Lines per Entity	250-300	15-20
Development Time	2-3 hours	5 minutes
Batch Insert (1000 records)	800ms	450ms
Large Dataset Retrieval (50K)	OutOfMemory	1.2s (streaming)
Memory Usage (1000 requests)	250MB	180MB

---

🔧 Configuration Reference

# Database auto-creation (default: true)
crudx:
  database:
    auto-create: true

# JPA Configuration
spring:
  jpa:
    hibernate:
      ddl-auto: update  # create, create-drop, validate, none
    properties:
      hibernate:
        format_sql: true
        use_sql_comments: true

# Performance Monitoring
crudx:
  performance:
    enabled: false
    dashboard-enabled: true
    dashboard-path: /crudx/performance
    track-memory: false
    max-stored-metrics: 1000
    retention-minutes: 60

# Custom Repository Packages (if needed)
crudx:
  jpa:
    repository.packages: com.myapp.repos
    entity.packages: com.myapp.entities
  mongo:
    repository.packages: com.myapp.mongo.repos

---

🤝 Comparison with Alternatives

Feature	CrudX	Spring Data REST	JHipster
Setup Time	5 minutes	30 minutes	Hours
Code Required	Minimal	Medium	High
Multi-DB Support	✅	❌	✅
Batch Operations	✅	❌	Partial
Performance Dashboard	✅	❌	❌
Learning Curve	Easy	Medium	Steep
Production Ready	✅	✅	✅
Custom Logic	✅	Limited	✅

---

🐛 Troubleshooting

Database Not Auto-Created

# Ensure auto-create is enabled
crudx:
  database:
    auto-create: true

Service Not Found Error

Issue: Service bean not found: employeeService

Solution: Ensure your entity extends the correct base class:

• CrudXMySQLEntity for MySQL
• CrudXPostgreSQLEntity for PostgreSQL
• CrudXMongoEntity for MongoDB

Performance Dashboard Not Loading

# Enable performance monitoring
crudx:
  performance:
    enabled: true
    dashboard-enabled: true

---

📚 Documentation

• Full API Documentation - Complete API reference
• Help Guide - Common issues and solutions
• Examples - Sample projects
• Wiki - Detailed guides

---

📝 What's Next?

Coming in v1.0.2:

• 🎯 DTO Support - Automatic Entity ↔ DTO mapping with complex nested objects

Stay tuned for exciting updates!

---

🤝 Contributing

Contributions are welcome! Please read our Contributing Guide for details.

---

👨‍💻 Author

Sachin Nimbal

• LinkedIn: linkedin.com/in/sachin-nimbal
• Email: sachinnimbal9@gmail.com

---

🧩 Framework Dependencies & Acknowledgements

CrudX is built on top of proven, production-grade open-source libraries to deliver a seamless, zero-boilerplate CRUD experience.

---

⚙️ Core Dependencies

• Spring Boot Web — REST endpoints and embedded Tomcat server
• Spring Boot Auto Configuration — automatic component configuration
• Spring Context & Transaction Management — DI and transaction support
• Spring Validation & AOP — request validation and cross-cutting concerns
• Jackson (Databind + JSR310) — JSON serialization with Java Time API support
• SLF4J — unified logging abstraction
• Thymeleaf — built-in internal dashboard / UI rendering
• Lombok — boilerplate reduction via annotations

---

🌐 API Documentation

• Springdoc OpenAPI (v2.3.0) — auto-generates Swagger UI and OpenAPI specs

---

🧩 Optional Integrations

• Spring Data JPA — relational persistence (MySQL, PostgreSQL)
• Spring Data MongoDB — NoSQL persistence support
• Jakarta Persistence API — JPA standard annotations and API
• MySQL & PostgreSQL Drivers — database connectivity

---

🧪 Testing Stack

• Spring Boot Test — integration testing support
• JUnit 5 — modern unit testing framework
• Testcontainers (MySQL, PostgreSQL, MongoDB) — lightweight, containerized DB testing
• Springdoc (Test) — validate API documentation during test phase

---

💡 Special thanks to the Spring, Jackson, Lombok, Springdoc, and Testcontainers communities for their open-source contributions that make CrudX possible.

---

⭐ Show Your Support

If CrudX helps your project, please give it a star! ⭐

---

Built and maintained with ❤️ by Sachin Nimbal
Licensed under the Apache License 2.0