Java Spring Boot REST API Boilerplate

A production-ready Java Spring Boot boilerplate for building scalable REST APIs with enterprise-grade patterns, comprehensive security, and AI-friendly architecture.

🚀 Quick Start

# Clone the repository
git clone [repository-url]
cd backend-java-spring-boot

# Build the project
mvn clean install

# Run the application
mvn spring-boot:run

# Access API documentation
open http://localhost:8080/swagger-ui.html

✨ Features

Core Features

✅ Layered Architecture: Clean separation with Controller/Service/Repository/Model
✅ RESTful API: Complete REST API with best practices
✅ Spring Security: JWT authentication and role-based authorization
✅ Data Persistence: Spring Data JPA with PostgreSQL
✅ API Documentation: Interactive Swagger UI with Springdoc OpenAPI
✅ Validation: Bean Validation with custom validators
✅ Exception Handling: Global exception handling
✅ Logging: Structured logging with SLF4J and Logback

Advanced Features

⚡ Caching: Redis (distributed) and Caffeine (local)
🔄 Async Processing: @Async support with custom thread pools
📨 Message Queuing: Kafka and RabbitMQ integration
⏰ Scheduled Tasks: @Scheduled tasks
📁 File Handling: File upload/download with validation
✉️ Email Service: Async email sending
🔌 WebSockets: Real-time communication patterns
📡 Event-Driven: Spring Events for decoupled communication

Development Features

🧪 Testing: Unit, integration, and e2e test patterns
📊 Monitoring: Spring Boot Actuator with custom metrics
🐳 Docker: Docker and Docker Compose support
🔄 Migrations: Flyway for version-controlled schema changes
🌍 Profiles: Dev, staging, production configurations
✅ Code Quality: Checkstyle, SpotBugs, PMD

🛠️ Tech Stack

Category	Technology
Runtime	Java 21 LTS
Framework	Spring Boot 3.x
Build Tool	Maven
Database	PostgreSQL (default)
ORM	Spring Data JPA + Hibernate
Authentication	Spring Security + JWT
API Docs	Springdoc OpenAPI
Testing	JUnit 5, Mockito, Spring Boot Test
Caching	Redis, Caffeine
Messaging	Kafka, RabbitMQ
Deployment	Docker, Kubernetes
Monitoring	Actuator, Micrometer

📋 Prerequisites

Java 21 or higher (Download)
Maven 3.8+ (Download)
PostgreSQL 14+ (Download) - Optional, H2 available for dev
Docker (Optional) - For containerized deployment

🏗️ Building from Source

You don't need to build from source to use this boilerplate, but if you want to customize or contribute:

Clone and Build

# Clone the repository
git clone [repository-url]
cd backend-java-spring-boot

# Build the project (skip tests for faster build)
mvn clean install -DskipTests

# Build with tests
mvn clean install

# Package as JAR
mvn clean package

Run Locally

# Using Maven
mvn spring-boot:run

# Using Java directly
java -jar target/spring-boot-api-0.0.1-SNAPSHOT.jar

# With specific profile
mvn spring-boot:run -Dspring-boot.run.profiles=dev

Verify Installation

# Check if application is running
curl http://localhost:8080/actuator/health

# Access Swagger UI
open http://localhost:8080/swagger-ui.html

🆘 Getting Help

Having trouble with the boilerplate? We're here to help!

Documentation

Getting Started Guide - Step-by-step tutorial for first-time users
Full Documentation - Complete project documentation
API Documentation - API specifications and examples
Troubleshooting Guide - Common issues and solutions

Community Support

Stack Overflow - Tag your questions with spring-boot and java
GitHub Discussions - Ask questions and discuss features
GitHub Issues - Report bugs and request features

Before Asking for Help

Search existing issues - Your question might already be answered
Check the documentation - Especially the Getting Started and Troubleshooting guides
Provide details - Include Spring Boot version, Java version, and error messages
Create a minimal reproducible example - Helps us help you faster

Reporting Issues

Found a bug? Please create an issue with:

Clear description of the problem
Steps to reproduce
Expected vs actual behavior
Environment details (Java version, OS, etc.)
Stack traces or error messages

See our Issue Template for more details.

📁 Project Structure

backend-java-spring-boot/
├── .ai/                    # AI-specific configuration
│   ├── context.yaml       # Project metadata
│   ├── mcp-config.json    # MCP server config
│   └── agent-instructions.md
├── .claude/                # Claude Code commands
│   ├── commands/          # Custom commands
│   └── output-style.md
├── docs/                   # Project documentation
│   ├── index.md           # Main documentation entry
│   ├── architecture/      # Architecture docs
│   ├── guides/            # Setup & deployment guides
│   ├── status/            # Current status tracking
│   ├── templates/         # Documentation templates
│   ├── session-management/ # AI session tracking
│   └── _working/          # Temporary work files
├── standards/              # Development standards
│   ├── coding.md          # Code conventions
│   ├── patterns.md        # Architectural patterns
│   ├── business-rules.md  # Domain logic
│   └── documentation.md   # Documentation standards
├── rules/                  # Spring Boot rules
│   ├── java-spring-boot-rules.md
│   └── questions.md
└── src/                    # Source code (to be created)
    ├── main/
    │   ├── java/
    │   └── resources/
    └── test/

🏗️ Architecture

This boilerplate follows a layered architecture pattern:

┌─────────────────────────────────────┐
│      Controller Layer (REST)        │  ← HTTP Requests/Responses
├─────────────────────────────────────┤
│         Service Layer               │  ← Business Logic
├─────────────────────────────────────┤
│       Repository Layer              │  ← Data Access
├─────────────────────────────────────┤
│         Model Layer                 │  ← Domain Entities
└─────────────────────────────────────┘

Key Principles:

Single Source of Truth
SOLID Principles
High Cohesion, Low Coupling
AI-Friendly Documentation

Core Modules

Module	Purpose	Example
config/	Application configuration, security, caching	`SecurityConfig.java`, `CacheConfig.java`
controller/	REST API endpoints	`UserController.java`
service/	Business logic implementation	`UserService.java`
repository/	Data access layer	`UserRepository.java`
model/entity/	JPA domain entities	`User.java`, `Product.java`
model/dto/	Data transfer objects	`UserDTO.java`, `CreateUserRequest.java`
security/	Authentication & authorization	`JwtTokenProvider.java`, `SecurityFilter.java`
exception/	Custom exceptions & handlers	`GlobalExceptionHandler.java`, `UserNotFoundException.java`
util/	Utility classes	`DateUtil.java`, `ValidationUtil.java`

📚 Documentation

Document	Description
Project Overview	Complete project overview
Setup Guide	Environment setup instructions
Architecture	System architecture details
API Documentation	API specifications
Coding Standards	Code conventions
Patterns	Architectural patterns
Business Rules	Domain logic

🧪 Testing

# Run all tests
mvn test

# Run with coverage
mvn verify

# Run specific test
mvn test -Dtest=UserServiceTest

# Run integration tests
mvn verify -P integration-tests

Coverage Target: 80%+

🚢 Deployment

Docker

# Build image
docker build -t spring-boot-api .

# Run container
docker run -p 8080:8080 spring-boot-api

# Using docker-compose
docker-compose up

Kubernetes

# Apply manifests
kubectl apply -f k8s/

# Check deployment
kubectl get pods

🔧 Configuration

Configuration files are located in src/main/resources/:

application.yml - Main configuration
application-dev.yml - Development profile
application-prod.yml - Production profile

Environment Variables

Variable	Description	Default
`DB_HOST`	Database host	localhost
`DB_PORT`	Database port	5432
`DB_NAME`	Database name	myapp
`DB_USERNAME`	Database username	postgres
`DB_PASSWORD`	Database password	-
`JWT_SECRET`	JWT signing secret	-
`JWT_EXPIRATION`	Token expiration (ms)	86400000

🤝 Contributing

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Follow coding standards in standards/coding.md
Write tests for your changes
Ensure tests pass (mvn test)
Update documentation
Commit changes (git commit -m 'feat: add amazing feature')
Push to branch (git push origin feature/amazing-feature)
Open a Pull Request

Commit Message Format

Follow conventional commits:

<type>(<scope>): <subject>

feat: new feature
fix: bug fix
docs: documentation
style: formatting
refactor: code restructure
test: tests
chore: maintenance

📊 Status

Phase: Documentation & Setup
Completion: 20%
Next: Core implementation

See progress.yaml for detailed status.

🤖 AI-Friendly

This boilerplate is designed for AI-assisted development:

MCP Integration: Model Context Protocol for AI agents
Structured Documentation: Machine-readable status tracking
Context Files: AI behavior guidelines and project metadata
Clear Patterns: Well-documented architectural patterns

📝 License

MIT License

🆘 Support

Documentation: See docs/index.md
Issues: GitHub Issues
Discussions: GitHub Discussions

🙏 Acknowledgments

Built with:

Made with ❤️ for the Java Spring Boot community

Last Updated: 2025-10-08

Name		Name	Last commit message	Last commit date
Latest commit History 3 Commits
.ai		.ai
.claude		.claude
docs		docs
rules		rules
src/main		src/main
standards		standards
BACKEND_ARCHITECTURE_GUIDE.md		BACKEND_ARCHITECTURE_GUIDE.md
CONFIGURATION_COMPLETE.md		CONFIGURATION_COMPLETE.md
README.md		README.md
SETUP_SUMMARY.md		SETUP_SUMMARY.md
overview.md		overview.md
pom.xml		pom.xml

TreesSoftware/supap-backend

Folders and files

Latest commit

History

Repository files navigation