clean-architecture
This skill guides you through building Spring Boot applications with clean architecture principles, ensuring domain logic stays independent of frameworks and infrastructure. Learn to structure layered packages, implement ports and adapters, apply domain-driven design tactical patterns, and maintain strict dependency rules that keep your codebase testable and maintainable.
Clean Architecture provides patterns for layered Spring Boot apps with framework-independent domain logic and testable code.
AI-generated summary based on this skill's SKILL.md
Install
giuseppe-trisciuoglio/developer-kit/clean-architecture · repository language: Python
git clone https://github.com/giuseppe-trisciuoglio/developer-kit
cp -r developer-kit/plugins/developer-kit-java/skills/clean-architecture ~/.claude/skills/clean-architecturenpx skillfed install giuseppe-trisciuoglio/developer-kit/clean-architectureFrequently asked questions
AI-generated answers based on this skill's SKILL.md and metadata
How do I structure a Spring Boot project using clean architecture?
clean-architecture guides you to organize Spring Boot applications into layers that keep domain logic independent of frameworks. Structure your packages by domain concerns (entities, value objects, aggregates, repositories), application services (use cases), and infrastructure adapters (controllers, persistence, external APIs). This separation ensures your core business rules remain testable and framework-agnostic, following the dependency rule where inner layers never depend on outer layers.
What is hexagonal architecture and how does it apply to Java?
clean-architecture teaches hexagonal architecture (ports and adapters pattern) for Java projects by defining clear boundaries between your domain and external systems. Ports are interfaces representing contracts your domain needs; adapters implement those ports to connect to Spring, databases, or APIs. This approach isolates domain logic from framework details, making your application testable without Spring context and easily swappable infrastructure components.
How can I apply domain-driven design tactical patterns to my Java project?
clean-architecture covers DDD tactical patterns including entities, value objects, aggregates, repositories, and domain events. Model your domain using these constructs: entities for mutable objects with identity, value objects for immutable domain concepts, aggregates as consistency boundaries, repositories as collection-like abstractions, and domain events to capture significant business occurrences. This keeps your domain model expressive and decoupled from persistence frameworks.
How do I refactor tightly coupled Spring Boot code into testable layered architecture?
clean-architecture shows how to separate concerns by extracting domain logic from controllers and repositories into application services (use cases). Replace framework dependencies with interfaces (ports), inject them via Spring's dependency injection, and map between DTOs and domain models at boundaries. This refactoring makes unit tests possible without Spring context, improves code reusability, and clarifies business logic flow.
How does clean-architecture keep domain logic independent of framework dependencies?
clean-architecture enforces strict dependency rules: your domain layer contains no Spring annotations, JPA imports, or external library references. Infrastructure adapters depend on domain ports (interfaces), never the reverse. Use dependency injection to wire adapters at application startup. This inversion ensures your core business rules remain portable, testable in isolation, and unaffected by framework upgrades or technology changes.
What are the best practices for repository pattern and entity mapping in clean architecture?
clean-architecture distinguishes between JPA entities (persistence models) and domain entities (business models). Create a repository port interface in your domain layer; implement it in infrastructure using Spring Data JPA. Map JPA entities to domain models at adapter boundaries, never expose JPA entities to application services. This separation allows you to change persistence technology without affecting business logic and keeps your domain model free from ORM concerns.
SKILL.md
rendered from the published skill — quoted content, verbatim
Clean Architecture, Hexagonal Architecture & DDD for Spring Boot
Overview
This skill provides comprehensive guidance for implementing Clean Architecture, Hexagonal Architecture (Ports & Adapters), and Domain-Driven Design tactical patterns in Java 21+ Spring Boot 3.5+ applications. It ensures clear separation of concerns, framework-independent domain logic, and highly testable codebases through proper layering and dependency management.
When to Use
- Architecting new Spring Boot applications with clear separation of concerns
- Refactoring tightly coupled code into testable, layered architectures
-
Implementing domain logic independent of frameworks and infrastructure
(truncated - see the full file via the links below)
Read as markdown · JSON record · Browse the source repository
File tree — 3 files
plugins/developer-kit-java/skills/clean-architecture/SKILL.md
plugins/developer-kit-java/skills/clean-architecture/references/java-clean-architecture.md
plugins/developer-kit-java/skills/clean-architecture/references/spring-boot-implementation.md