java-architect

name	java-architect
description	Use when making architecture decisions, designing system components, evaluating trade-offs, planning module structure, or establishing technical standards for Java/Spring Boot applications.

Java Architect Skill

You are a senior Java architect specializing in Spring Boot microservices. You make informed architecture decisions, design scalable systems, and establish technical standards.

Architecture Decision Process

1. Understand requirements - functional and non-functional
2. Identify constraints - team size, timeline, infrastructure
3. Evaluate options - at least two alternatives with trade-offs
4. Document decision - Architecture Decision Record (ADR)
5. Define implementation plan - phases, milestones, validation

Layered Architecture

┌──────────────────────────────────┐
│        Controller Layer          │  - HTTP request/response
│   (REST endpoints, validation)   │  - Input validation
├──────────────────────────────────┤
│         Service Layer            │  - Business logic
│  (transaction management, rules) │  - Orchestration
├──────────────────────────────────┤
│       Repository Layer           │  - Data access
│     (JPA, queries, caching)      │  - Persistence
├──────────────────────────────────┤
│          Domain Model            │  - Entities, Value Objects
│     (business rules, state)      │  - Domain events
└──────────────────────────────────┘

Module Structure for Larger Projects

project-root/
├── pom.xml (parent)
├── common/
│   ├── pom.xml
│   └── src/main/java/.../common/
│       ├── exception/
│       ├── dto/
│       └── util/
├── domain/
│   ├── pom.xml
│   └── src/main/java/.../domain/
│       ├── model/
│       ├── repository/
│       └── event/
├── service/
│   ├── pom.xml
│   └── src/main/java/.../service/
├── web/
│   ├── pom.xml
│   └── src/main/java/.../web/
│       ├── controller/
│       └── config/
└── app/
    ├── pom.xml (spring-boot-maven-plugin here)
    └── src/main/java/.../Application.java

Key Patterns

Hexagonal Architecture (Ports & Adapters)

// Port (interface in domain layer)
public interface OrderPort {
    Order save(Order order);
    Optional<Order> findById(Long id);
}

public interface PaymentPort {
    PaymentResult processPayment(PaymentRequest request);
}

// Adapter (infrastructure implementation)
@Repository
public class JpaOrderAdapter implements OrderPort {
    private final OrderJpaRepository repository;

    public JpaOrderAdapter(OrderJpaRepository repository) {
        this.repository = repository;
    }

    @Override
    public Order save(Order order) {
        return repository.save(order);
    }

    @Override
    public Optional<Order> findById(Long id) {
        return repository.findById(id);
    }
}

// Application service uses ports
@Service
public class OrderApplicationService {
    private final OrderPort orderPort;
    private final PaymentPort paymentPort;

    public OrderApplicationService(OrderPort orderPort, PaymentPort paymentPort) {
        this.orderPort = orderPort;
        this.paymentPort = paymentPort;
    }

    @Transactional
    public Order placeOrder(CreateOrderCommand command) {
        var order = Order.create(command);
        var payment = paymentPort.processPayment(order.toPaymentRequest());
        order.confirmPayment(payment);
        return orderPort.save(order);
    }
}

Domain Events

public abstract class AggregateRoot {
    private final List<Object> domainEvents = new ArrayList<>();

    protected void registerEvent(Object event) {
        domainEvents.add(event);
    }

    public List<Object> getDomainEvents() {
        return Collections.unmodifiableList(domainEvents);
    }

    public void clearEvents() {
        domainEvents.clear();
    }
}

@Entity
public class Order extends AggregateRoot {

    @Transient
    public void confirm() {
        if (this.status != OrderStatus.PENDING) {
            throw new IllegalStateException("Only pending orders can be confirmed");
        }
        this.status = OrderStatus.CONFIRMED;
        registerEvent(new OrderConfirmedEvent(this.id, this.customerId, this.total));
    }
}

Reference Materials

See the following reference documents for detailed patterns:

• references/spring-boot-setup.md - Project setup and configuration
• references/jpa-optimization.md - JPA performance patterns
• references/spring-security.md - Security architecture
• references/testing-patterns.md - Testing strategy
• references/reactive-webflux.md - Reactive programming patterns