Java Micronaut Ddd

Java/Micronaut Development Standards

Core Principles

1. Domain-Driven Design (DDD)

Structure code around business capabilities, not technical layers. See docs/ddd-patterns.md for patterns and examples.

Avoid: technical-layer slicing

com.acme.app.controller
com.acme.app.service
com.acme.app.repository

Prefer: business modules (bounded contexts)

com.acme.app/
+-- billing/
|   +-- domain/         # Invoice, Payment, Money, BillingPolicy
|   +-- application/    # IssueInvoiceUseCase, RecordPaymentUseCase
|   +-- infrastructure/ # JooqInvoiceRepository, PaymentGatewayClient
|   `-- api/            # BillingController, request/response DTOs
+-- catalog/
|   +-- domain/
|   +-- application/
|   +-- infrastructure/
|   `-- api/
`-- identity/
    `-- ...

Key rules:

• Top-level packages are business modules (bounded contexts)
• Technical layers (domain/application/infrastructure/api) are inside each module
• A change like "adjust invoice rules" should touch one module (billing/), not hop across layers
• Cross-module calls go through explicit APIs (use cases, ports, domain events)

2. No Lombok

Write explicit Java code. Do not use Lombok annotations (@Data, @Getter, @Builder, etc.).

Why: Explicit code is debuggable, IDE-friendly, and avoids compile-time magic issues.

Instead of Lombok:

• Use Java records for immutable data carriers
• Generate getters/setters via IDE
• Write explicit builders when needed
• Use Objects.equals() and Objects.hash() for equals/hashCode

3. Conservative Dependency Management

Before adding a new library:

1. Check if functionality exists in current dependencies
2. Check if Micronaut modules already provide it
3. Check if Java standard library covers the use case

Analyze classpath first:

./mvnw dependency:tree
# or
./gradlew dependencies

4. jOOQ Persistence

Use jOOQ with Micronaut SQL for relational persistence. Do not introduce Micronaut Data, JPA, or Hibernate for persistence in this skill.

• Schema: Model persistence from migrations/DDL and generated jOOQ schema types
• Queries: Use explicit DSLContext queries, joins, projections, and locking
• Repositories: Keep domain repository interfaces as ports; implement them with jOOQ in infrastructure
• Mapping: Convert between jOOQ records and domain objects at the adapter boundary
• Transactions: Use @Transactional on application service methods; use explicit version columns for optimistic locking

See docs/data-access.md for jOOQ repository and mapping patterns. See docs/transactions.md for transaction management rules.

5. Testcontainers for Integration Testing

Use Testcontainers or Micronaut Test Resources for tests requiring external dependencies (databases, message brokers, Redis, etc.).

See docs/testing.md for setup and patterns.

6. MapStruct for DTO Mapping

Use MapStruct for structural conversions between API DTOs, use-case commands, and responses. Enforce strict boundaries:

• Controllers: Accept/return DTOs only, never touch domain objects or jOOQ records directly
• Services/Use cases: Invoke mappers, resolve relationships by ID, call domain behavior
• Mappers: Pure structural conversion only, no repository access, no business logic
• Domain: Independent of DTOs, web layer, jOOQ records, and SQL details

See docs/mapping.md for patterns and examples.

7. Micronaut Redis Access

Use Micronaut Redis module according to official docs: https://micronaut-projects.github.io/micronaut-redis/6.9.0/guide/

• Prefer Micronaut-provided Redis clients/configuration before introducing custom wrappers
• Keep Redis usage behind ports/adapters in the infrastructure layer
• Use serialization and key naming conventions explicitly
• For tests that depend on Redis, use Testcontainers instead of shared local instances

See docs/redis-access.md for usage guidance.

Workflow

Before Writing Code

1. Analyze existing dependencies:

   ./mvnw dependency:tree | grep -E "(micronaut-jooq|jooq|micronaut-data|hibernate|jakarta.persistence|micronaut-validation|micronaut-redis|lombok|mapstruct|test)"
   

2. Verify jOOQ stack: Ensure micronaut-jooq, jOOQ code generation, a DataSource, and migrations are configured.

3. Check for forbidden persistence stack: If Micronaut Data, JPA, or Hibernate are present, discuss removal or isolation before adding persistence code.

4. Check for MapStruct: If not present and DTOs are needed, add mapstruct + mapstruct-processor.

5. Check for Lombok: If lombok is in dependencies, discuss removal strategy with user before proceeding.

When Implementing Features

1. Start with domain model - domain entities and value objects
2. Define repository interfaces (ports) - in domain/application layer
3. Create DTOs - request/response records per use case
4. Create MapStruct mappers - pure DTO/command/response conversion
5. Implement application services/use cases - orchestrate domain operations and transactions
6. Implement infrastructure adapters - jOOQ repositories, Redis adapters, external clients
7. Add API layer last - controllers are thin adapters, DTOs only

When Writing Tests

1. Unit tests - domain logic, no Micronaut context
2. Integration tests - use @MicronautTest + Testcontainers or Micronaut Test Resources
3. Focused tests - test jOOQ repository/client behavior with minimal required context

Quick Reference

Reference Files

• DDD Patterns - Aggregates, entities, value objects, domain events
• Data Access - jOOQ repositories, generated schema types, explicit SQL
• Transactions - transaction boundaries, propagation, locking
• Testing - Testcontainers setup and integration test patterns
• Mapping - MapStruct patterns, layer boundaries, DTO design
• Redis Access - Micronaut Redis integration and adapter patterns
• Micronaut guide - https://docs.micronaut.io/4.10.21/guide/
• Micronaut SQL/jOOQ guide - https://micronaut-projects.github.io/micronaut-sql/latest/guide/
• Micronaut Redis guide - https://micronaut-projects.github.io/micronaut-redis/6.9.0/guide/