a-pavithraa/springboot-skills-marketplace / plugins/springboot-architecture/skills/creating-springboot-projects
creating-springboot-projects
VerifiedUse when starting a new Spring Boot project or service: scaffolding or bootstrapping a backend, REST API, microservice or modular monolith; choosing how to structure it (layered, package-by-module, modular monolith, tomato, DDD-hexagonal); selecting Spring Boot 4 features; generating the base project with progen or Spring Initializr; or applying the bundled templates and references in this skill. Not for migrating existing projects or for isolated JPA/repository work without broader project-creation context.
references/architecture-guide.md
View on GitHub# Spring Boot Architecture Patterns Guide
## Table of Contents
1. [Architecture Decision Matrix](#architecture-decision-matrix)
2. [Package Structures](#package-structures)
3. [Naming Conventions](#naming-conventions)
4. [Anti-Patterns to Avoid](#anti-patterns-to-avoid)
5. [Architecture Upgrade Path](#architecture-upgrade-path)
6. [Best Practices](#best-practices)
---
## Architecture Decision Matrix
| Criteria | Layered | Package-by-Module | Modulith | Tomato | DDD+Hex |
|----------|---------|-------------------|----------|--------|---------|
| Team Size | 1-3 | 3-10 | 5-15 | 5-15 | 10+ |
| Lifespan | Months | 1-2 yrs | 2-5 yrs | 3-5 yrs | 5+ yrs |
| Type Safety | Low | Low | Low | High | High |
| Learning Curve | ⭐ | ⭐⭐ | ⭐⭐ | ⭐⭐⭐ | ⭐⭐⭐⭐ |
## Package Structures
### Layered Architecture
```
com.example.app/
├── controller/
├── service/
├── repository/
└── domain/
```
**When to use:** Simple CRUD applications, prototypes, MVPs, single developer projects.
### Package-by-Module
```
com.example.app/
├── products/
│ ├── domain/
│ └── rest/
├── orders/
│ ├── domain/
│ └── rest/
└── shared/
```
**When to use:** 3-5 distinct features, medium-sized applications, need feature isolation.
### Modular Monolith (Spring Modulith)
```
com.example.app/
├── products/
│ ├── internal/ ← Package-private implementations
│ ├── ProductsAPI.java ← Public module API
│ └── domain/
├── orders/
│ ├── internal/
│ ├── OrdersAPI.java
│ └── domain/
└── shared/
```
**When to use:** Need enforced module boundaries, want to test module independence, planning potential microservices extraction.
### Tomato Architecture
```
com.example.app/
├── products/
│ ├── domain/
│ │ ├── vo/
│ │ │ ├── ProductSKU.java
│ │ │ ├── Price.java
│ │ │ └── Quantity.java
│ │ ├── ProductEntity.java
│ │ ├── ProductService.java
│ │ └── ProductQueryService.java
│ └── rest/
│ ├── ProductController.java
│ └── converters/
│ └── StringToProductSKUConverter.java
└── shared/
└── vo/
├── Money.java
└── Email.java
```
**When to use:** Rich domain models, need type safety, financial/healthcare domains, experiencing validation bugs from primitive types.
### DDD+Hexagonal Architecture
```
com.example.app/
├── products/
│ ├── application/
│ │ ├── command/
│ │ │ ├── CreateProductHandler.java
│ │ │ └── UpdateProductHandler.java
│ │ └── query/
│ │ └── ProductQueryService.java
│ ├── domain/
│ │ ├── model/
│ │ │ ├── ProductAggregate.java
│ │ │ └── ProductFactory.java
│ │ ├── vo/
│ │ │ ├── ProductSKU.java
│ │ │ └── Price.java
│ │ └── ports/
│ │ └── ProductRepository.java (interface)
│ ├── infra/
│ │ └── persistence/
│ │ └── JpaProductRepository.java (impl)
│ └── interfaces/
│ └── rest/
│ └── ProductController.java
└── shared/
└── domain/
```
**When to use:** Complex business domains, CQRS needed, infrastructure independence required, 10+ team members, 5+ year lifespan.
## Naming Conventions
### Tomato/DDD Patterns
| Type | Pattern | Example | Package |
|------|---------|---------|---------|
| Entity | `*Entity` | `ProductEntity` | `domain/model/` |
| Aggregate Root | `*Aggregate` | `OrderAggregate` | `domain/model/` |
| Value Object | Domain name | `ProductSKU`, `Price`, `Email` | `domain/vo/` |
| Command | `*Cmd` | `CreateProductCmd` | `application/command/` |
| Command Handler | `*Handler` | `CreateProductHandler` | `application/command/` |
| View Model | `*VM` | `ProductVM` | `domain/models/` or `interfaces/rest/dto/` |
| Write Service | `*Service` | `ProductService` | `domain/` |
| Read Service | `*QueryService` | `ProductQueryService` | `application/query/` |
| Repository Interface | `*Repository` | `ProductRepository` | `domain/ports/` (DDD) or `domain/` |
| Repository Impl | `Jpa*Repository` | `JpaProductRepository` | `infra/persistence/` |
| Module API | `*API` | `ProductsAPI` | Package root |
| Converter | `StringTo*Converter` | `StringToProductSKUConverter` | `rest/converters/` |
### General Conventions
- Use plural names for feature/module packages: `products/` not `product/`
- Value Objects are immutable and use `of()` factory method
- Commands are immutable records
- View Models are immutable records for API responses
- Aggregates encapsulate business logic and invariants
## Anti-Patterns to Avoid
| Don't | Do | Why |
|-------|-----|-----|
| Jump to implementation | Ask assessment questions first | Prevents over-engineering or under-engineering |
| Use DDD for simple CRUD | Use Layered or Package-by-Module | DDD adds complexity without benefit for simple cases |
| Use Layered for complex domain | Use Tomato or DDD+Hexagonal | Layered architecture leads to anemic domain models |
| Skip infrastructure | Always include Flyway, Testcontainers, Docker | Production readiness requires proper infrastructure |
| Copy templates blindly | Read template comments, adapt to domain | Templates are starting points, not solutions |
| Primitive obsession | Use Value Objects for domain concepts | Type safety prevents bugs, makes intent explicit |
| Anemic domain model | Put business logic in entities/aggregates | Domain-Driven Design principle |
| God services | Split by command/query responsibility | CQRS improves maintainability |
| Shared mutable state | Use immutable Value Objects | Thread-safety and predictability |
## Architecture Upgrade Path
### When to Upgrade
| From | To | Trigger | Effort |
|------|-----|---------|--------|
| Layered | Package-by-Module | 3+ features, team grows to 3+ | Low |
| Package-by-Module | Modular Monolith | Need enforced boundaries, testing independence | Medium |
| Modular Monolith | Tomato | Type confusion bugs, validation scattered across layers | Medium |
| Tomato | DDD+Hexagonal | Need infrastructure independence, CQRS, complex business rules | High |
### Migration Strategies
**Layered → Package-by-Module:**
1. Create module packages (products/, orders/)
2. Move related controllers, services, repos into modules
3. Extract shared utilities to shared/
4. Refactor cross-module dependencies
**Package-by-Module → Modular Monolith:**
1. Add Spring Modulith dependency
2. Create `*API.java` interfaces for each module
3. Make internal classes package-private
4. Add `@ApplicationModuleTest` for module verification
5. Use `modularity-test.java` template
**Modular Monolith → Tomato:**
1. Identify domain concepts currently using primitives
2. Create Value Objects for each concept (SKU, Price, Email, etc.)
3. Replace primitives in entities with VOs
4. Add Spring Converters for @PathVariable binding
5. Update tests to use VOs
**Tomato → DDD+Hexagonal:**
1. Separate commands from queries (CQRS)
2. Create application layer with handlers
3. Define domain ports (repository interfaces in domain/)
4. Move infrastructure implementations to infra/
5. Extract aggregates from entities
6. Add ArchUnit tests for hexagonal verification
### Signs You've Outgrown Your Architecture
**Layered:**
- Features span multiple unrelated domains
- Service classes exceed 500 lines
- Difficult to understand feature scope
- Changes affect multiple unrelated features
**Package-by-Module:**
- Modules have circular dependencies
- Difficult to test modules in isolation
- Unclear module boundaries
- Need to extract microservices
**Modular Monolith:**
- Type confusion bugs (mixing IDs, codes, values)
- Validation logic scattered everywhere
- Primitive parameters causing bugs
- Financial/healthcare domain (needs type safety)
**Tomato:**
- Complex business rules in multiple aggregates
- Need to swap infrastructure (database, message queue)
- Multiple teams working on same codebase
- Planning microservices extraction
## Best Practices
### Start Simple
- Begin with Layered or Package-by-Module
- Don't prematurely optimize for scale
- Upgrade architecture when complexity demands it
- Measure complexity by team size, lifespan, and domain complexity
### Type Safety
- Use Value Objects for domain concepts (not just primitives)
- Leverage Java records for immutability
- Enable JSpecify null-safety (@NullMarked)
- Use sealed classes for states/enums when appropriate
### Module Boundaries
- Each module should have clear responsibility
- Minimize dependencies between modules
- Use events for cross-module communication
- Test modules independently
### Infrastructure
- Always use migrations (Flyway/Liquibase)
- Always use Testcontainers for integration tests
- Always use Docker Compose for local development
- Always use ProblemDetail for REST error responses
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |