- JAX-RS resource langsung query database
- DTO API dipakai sebagai entity database
- mapper melakukan network call
- static utility membaca environment variable
- singleton menyimpan request-specific state
- ThreadLocal tidak dibersihkan
- feature flag dievaluasi di tempat acak
- transaction boundary tersebar di banyak layer

Architecture is not mainly about folders.
Architecture is about dependency direction, lifecycle ownership, state ownership, and failure boundaries.

- dipahami
- dites
- diubah
- diobservasi
- diamankan
- direview
- dioperasikan

Change one API response field
  -> breaks database mapping
  -> breaks Kafka event
  -> breaks UI client
  -> breaks integration test

Resource/API layer
  -> Application service / use case layer
      -> Domain layer
      -> Repository port
      -> Integration port
  -> Infrastructure adapters
      -> PostgreSQL/MyBatis/JDBC
      -> Kafka producer/consumer
      -> HTTP clients
      -> Redis
      -> Cloud SDK

Outer layers know transport and infrastructure.
Inner layers know business meaning and invariants.

- path/query/header/form extraction
- request DTO acceptance
- authentication context access
- basic API validation trigger
- call application service/use case
- map result to HTTP response
- map known errors via exception strategy

- direct SQL
- direct Kafka publishing
- complex domain decision
- manual transaction choreography
- hidden retry logic
- long-running blocking orchestration without explicit design

@Path("/quotes")
@Consumes(MediaType.APPLICATION_JSON)
@Produces(MediaType.APPLICATION_JSON)
public class QuoteResource {
    private final CreateQuoteUseCase createQuote;

    public QuoteResource(CreateQuoteUseCase createQuote) {
        this.createQuote = createQuote;
    }

    @POST
    public Response create(CreateQuoteRequest request, @Context SecurityContext securityContext) {
        CreateQuoteCommand command = CreateQuoteCommand.from(request, securityContext);
        QuoteResult result = createQuote.execute(command);
        return Response.status(Response.Status.CREATED)
                .entity(QuoteResponse.from(result))
                .build();
    }
}

- transaction boundary orchestration
- call domain policy
- call repository port
- call integration port
- enforce workflow step
- produce domain/event intent
- apply idempotency policy

- JAX-RS annotations
- HTTP status codes
- servlet context access
- JSON serialization concerns
- database-specific SQL details

public final class CreateQuoteUseCase {
    private final QuoteRepository quoteRepository;
    private final PricingPort pricingPort;
    private final QuoteEventPublisher eventPublisher;

    public QuoteResult execute(CreateQuoteCommand command) {
        Quote quote = Quote.createDraft(command);
        Price price = pricingPort.price(quote);
        quote.applyPrice(price);

        quoteRepository.save(quote);
        eventPublisher.publishQuoteCreated(quote);

        return QuoteResult.from(quote);
    }
}

- quote state transition
- quote validity
- product compatibility
- pricing invariant
- catalog effective date
- order submission precondition
- tenant-specific business rule boundary

- database connection
- JAX-RS annotations
- Kafka producer
- HTTP client
- cloud SDK
- environment variable lookup

public interface QuoteRepository {
    Optional<Quote> findById(QuoteId id);
    void save(Quote quote);
}

public final class MyBatisQuoteRepository implements QuoteRepository {
    private final QuoteMapper mapper;

    @Override
    public Optional<Quote> findById(QuoteId id) {
        return mapper.findById(id.value()).map(QuoteRowMapper::toDomain);
    }
}

- returns database entity directly to resource
- exposes SQL details to application service
- performs HTTP calls
- publishes Kafka events implicitly
- starts hidden transaction

- downstream HTTP service
- Kafka producer/consumer
- Redis
- cloud SDK
- file/object storage
- workflow engine

public interface PricingPort {
    Price price(Quote quote);
}

public final class HttpPricingClient implements PricingPort {
    private final Client client;

    @Override
    public Price price(Quote quote) {
        // HTTP-specific code stays here
    }
}

Application service does not care whether pricing comes from HTTP, local library, cache, or workflow task.

Resource -> Application -> Domain
Application -> Port interfaces
Infrastructure -> Port interfaces

Domain -> JAX-RS
Domain -> MyBatis
Domain -> Kafka
Domain -> Redis
Domain -> System.getenv

grep -R "jakarta.ws.rs" src/main/java/com/example/domain
grep -R "org.apache.ibatis" src/main/java/com/example/domain
grep -R "org.apache.kafka" src/main/java/com/example/domain

API DTO changes because client contract changes.
Domain model changes because business rule changes.
Persistence entity/row changes because database schema changes.
Event DTO changes because event contract changes.

public class Quote {
    @JsonProperty("quoteId")
    @Column(name = "quote_id")
    @NotNull
    private String quoteId;
}

- JSON serialization
- database mapping
- validation
- domain identity

CreateQuoteRequest      -> API input
CreateQuoteCommand      -> application input
Quote                   -> domain model
QuoteRecord / QuoteRow  -> persistence representation
QuoteCreatedEvent       -> event contract
QuoteResponse           -> API output

For small/simple services, reuse can reduce boilerplate.
For enterprise systems with long-lived contracts, separation reduces blast radius.

- static mutable map
- static current tenant
- ThreadLocal user context
- System properties
- environment variable lookup inside business logic
- singleton cache with mutable values
- global service locator
- global ObjectMapper mutation
- clock accessed through Instant.now()
- random UUID generated in deep logic
- default timezone
- default locale

Same input does not always produce same output.

public final class MoneyFormat {
    public static String format(BigDecimal value, Currency currency) {
        return value.setScale(2, RoundingMode.HALF_UP) + " " + currency;
    }
}

public final class TenantContextUtil {
    private static final ThreadLocal<String> CURRENT_TENANT = new ThreadLocal<>();

    public static String currentTenant() {
        return CURRENT_TENANT.get();
    }
}

public record RequestContext(
        String correlationId,
        TenantId tenantId,
        UserId userId
) {}

@Singleton
public final class QuoteMapper {
    public QuoteResponse toResponse(Quote quote) {
        return new QuoteResponse(...);
    }
}

@Singleton
public final class QuoteWorkflowState {
    private String currentQuoteId;

    public void setCurrentQuoteId(String id) {
        this.currentQuoteId = id;
    }
}

Singleton object must not hold request-specific mutable state.

- not cleared after request
- used across executor boundary
- used in async task
- reused by container thread pool
- treated as domain dependency

request A sets tenantId = TENANT_A
thread returns to pool
request B handled by same thread
tenantId still TENANT_A
request B reads wrong tenant context

- set context at boundary
- clear context in finally block
- propagate context explicitly to executors
- avoid using ThreadLocal for domain decisions

public class QuoteService {
    public QuoteRepository repository() {
        return GlobalServiceLocator.get(QuoteRepository.class);
    }
}

- dependencies invisible
- tests harder
- startup failure delayed
- circular dependency hidden
- runtime behavior harder to analyze

public class QuoteService {
    private final QuoteRepository repository;

    public QuoteService(QuoteRepository repository) {
        this.repository = repository;
    }
}

public BigDecimal calculatePrice(...) {
    String roundingMode = System.getenv("ROUNDING_MODE");
    ...
}

public record PricingConfig(
        RoundingMode roundingMode,
        int scale,
        boolean enableNewTaxRule
) {}

public final class PricingPolicy {
    private final PricingConfig config;

    public PricingPolicy(PricingConfig config) {
        this.config = config;
    }
}

- validation
- testing
- documentation
- config fingerprinting
- safe defaults

resource checks flag
service checks same flag differently
repository checks another flag
mapper checks hidden flag

- evaluate flag at clear decision boundary
- pass decision as explicit policy/input
- log/audit important decisions
- keep default safe

public QuoteResult execute(CreateQuoteCommand command) {
    PricingMode mode = flagEvaluator.pricingMode(command.tenantId());
    return pricingWorkflow.createQuote(command, mode);
}

- application service method
- repository method
- framework annotation/interceptor
- database function/procedure

application service believes save + publish are atomic
repository actually commits early
Kafka publish fails
DB state exists without event

- define transaction owner
- use outbox for DB + event consistency
- avoid hidden commits inside repository
- document propagation rule

com.company.quote
  api
    QuoteResource.java
    request
    response
    mapper
  application
    CreateQuoteUseCase.java
    SubmitQuoteUseCase.java
    command
    result
  domain
    Quote.java
    QuoteStatus.java
    PricingPolicy.java
    TenantRule.java
  port
    QuoteRepository.java
    PricingPort.java
    EventPublisher.java
  infrastructure
    db
      mybatis
      jdbc
    kafka
    http
    redis
    cloud
  config
    QuoteServiceConfig.java
  observability
    LoggingFilter.java
    TraceConfig.java

Can dependencies be understood and controlled?

HTTP request -> resource -> mocked use case -> HTTP response

command -> use case -> fake repository/integration port -> result/state

domain object/policy -> pure business behavior

repository -> real PostgreSQL/Testcontainers -> SQL mapping

publisher/consumer -> test Kafka -> event contract

- request log
- status code
- route template
- latency
- correlation ID

- use case started/completed
- business outcome
- important decision

- DB query metrics
- downstream call latency
- Kafka publish/consume result
- retry/circuit breaker events

- API field rename breaks persistence
- DB column addition appears in response unintentionally
- serialization annotation changes query mapping

Separate API DTO and persistence row/entity.

- domain tests require database or Kafka
- business logic hard to run locally
- infrastructure outage affects pure policy test

Introduce ports/interfaces and adapters.

- cross-tenant data leak
- intermittent authorization failure
- logs show wrong tenant

Explicit request context, clear ThreadLocal, propagation wrapper, negative tenant tests.

- data from request A appears in request B
- concurrency-only failures
- flaky integration tests

Make singleton stateless, immutable, or thread-safe. Move request state to request-scoped object.

- test passes locally but fails in CI
- pod behavior differs by env
- runtime change invisible in dependency graph

Typed config loaded once, validated, injected, and logged as safe fingerprint.

- mapping unexpectedly calls database/service
- response building becomes slow
- serialization triggers external call

Keep mappers pure. Fetch data explicitly before mapping.

Package/layering:
- What are the top-level modules/packages?
- Is there a clear resource/application/domain/infrastructure boundary?
- Do domain packages import JAX-RS, MyBatis, Kafka, Redis, or cloud SDK?
- Are use cases explicit or is logic mostly inside resources/repositories?

Model separation:
- Are API DTOs separate from persistence entities/rows?
- Are event DTOs separate from API response DTOs?
- Is MapStruct or manual mapping used?
- Are serialization annotations leaking into domain models?

Dependency injection:
- Is constructor injection preferred?
- Are dependencies visible in constructors?
- Is service locator used directly in application code?
- Are singleton/request scopes documented?

State:
- Are there static mutable fields?
- Are ThreadLocals used?
- Are ThreadLocals cleared?
- Are singleton beans stateless/thread-safe?
- Are caches tenant-aware?

Configuration:
- Is config accessed through typed config objects?
- Are environment variables read deep inside business logic?
- Is config validated at startup?
- Are feature flags evaluated at clear boundaries?

Transactions:
- Where is transaction boundary defined?
- Do repositories commit internally?
- Is DB + event consistency handled by outbox or another pattern?

Testing:
- Can domain/application logic be tested without container?
- Are integration tests targeted to infrastructure adapters?
- Are resource tests separated from use case tests?

Boundary:
- Is this logic in the right layer?
- Does resource code contain business orchestration?
- Does domain code depend on infrastructure?
- Does mapper perform side effects?

Dependency:
- Are dependencies explicit?
- Is constructor injection used?
- Is service locator/global lookup avoided?
- Are circular dependencies introduced?

State:
- Is any mutable state shared across requests?
- Is singleton state safe?
- Is ThreadLocal usage cleared and propagated correctly?
- Is tenant/user/request context explicit?

Models:
- Are API/domain/entity/event models separated where needed?
- Does this change accidentally break contract compatibility?
- Are mapping tests needed?

Config/flags:
- Is config typed and validated?
- Are feature flags evaluated in a controlled place?
- Are defaults safe?

Tests:
- Is there a unit test at the right layer?
- Is there an integration test for infrastructure behavior?
- Are negative and concurrency cases covered when relevant?

A dependency not visible in constructor or method input is probably hidden coupling.

A model reused across API, DB, domain, and event layers is a future compatibility trap.

Static mutable state in a server should be assumed dangerous until proven otherwise.

ThreadLocal is a boundary tool, not a business model.

Mappers should not perform I/O.

Repositories should not secretly publish events.

A package structure is good only if dependency direction and lifecycle ownership are clear.

- resource layer for HTTP concerns
- application layer for use case orchestration
- domain layer for business invariants
- repository/integration ports for external boundaries
- infrastructure adapters for protocols and tools
- explicit dependency injection
- typed configuration
- controlled feature flag evaluation
- minimal hidden global state
- clear transaction ownership
- targeted tests per layer

Can a future engineer change one concern without accidentally changing transport, persistence, events, tenant behavior, and runtime state at the same time?