Architecture on 0AndWild_log

Designing a Product Ranking System

Fri, 17 Jul 2026 16:20:00 +0900

TL;DR

I designed a daily product ranking system based on user behavior events.

My first approach published product views, likes, and successful payments to Kafka. commerce-streamer consumed the events and updated ranking scores in a Redis Sorted Set in real time. Redis was a good fit as a serving store because it supports fast Top N queries and rank lookups for individual products.

As I worked through the design, though, I began to question whether Redis should be the ranking system’s only Source of Truth. Expired or lost data is difficult to recover, and changing weights requires historical metrics if we want to recalculate past scores. Supporting hourly, weekly, and monthly rankings makes retaining those source metrics even more important.

This post starts with the Redis design, then explores an alternative that stores source metrics in an RDB and uses Redis to serve only the Top N results needed for queries.

My first reading of the requirements

Initially, ranking sounded like a simple matter of calculating a score for each product and sorting the results.

On closer inspection, the more important question was how to interpret different user actions.

A product detail view signals interest, but less strongly than a purchase. A like is stronger than a view, but doesn’t necessarily lead to revenue. A successful payment is the strongest signal, yet using the sales amount directly could let expensive products dominate the ranking.

I used the following signals:

Event	Meaning	Ranking effect
Product detail view	Mild interest	Increase view score
Like	Explicit interest	Increase like score
Unlike	Withdrawn interest	Decrease like score
Successful payment	Purchase conversion	Increase sales score

Views, likes, and sales use different units, so I kept their metrics separate and applied weights when calculating the final score.

score = carry
 + viewCount * viewWeight
 + likeCount * likeWeight
 + ln(1 + salesAmount) * salesWeight

The sales contribution is based on price * quantity, with a logarithm applied. Using the raw amount could give expensive or already popular products an excessive, persistent advantage once they reach the top.

First design: real-time Redis rankings

My first design used Redis as the real-time ranking store.

The flow is roughly:

A user views a product, likes it, or pays for an order.
commerce-api records a domain event.
The event is stored in a transaction outbox.
An outbox relay publishes it to a Kafka topic.
commerce-streamer consumes the event.
It updates the metrics and final score in the daily Redis ranking keys according to the event type.
The ranking API reads ranks and scores from Redis, adds product information from MySQL, and returns the response.

The outbox addresses the gap between the API transaction and Kafka publication. If an order or like change commits but its event fails to publish, ranking data can drift from the actual state. Recording the outbox row in the same transaction as the domain change lets a relay publish it separately.

Why use date-specific Redis keys?

These are daily rankings, so the keys include a date.

ranking:metric:view:{yyyyMMdd}
ranking:metric:like:{yyyyMMdd}
ranking:metric:sales:{yyyyMMdd}
ranking:metric:raw-sales-amount:{yyyyMMdd}
ranking:metric:carry:{yyyyMMdd}
ranking:all:{yyyyMMdd}
ranking:processed:{yyyyMMdd}

I separated the metric keys because weights can change.

If we store only the final score, changing viewWeight or likeWeight leaves us without enough information to reinterpret the old value. Separate view, like, and sales metrics let us recalculate ranking:all:{date} using the current weights.

ranking:processed:{date} tracks duplicate events. Kafka consumers may process messages at least once, which means the same event can arrive again. If an eventId has already been processed, it must not increase the score a second time.

What worked well about Redis

A Redis Sorted Set felt like a natural match for ranking: it stores members with scores and supports fast retrieval in score order.

ZINCRBY ranking:metric:view:20260717 1 productId
ZREVRANGE ranking:all:20260717 0 19 WITHSCORES
ZREVRANK ranking:all:20260717 productId

Redis commands cover both Top N queries and rank lookups for a specific product.

The API doesn’t need to run expensive aggregations. It reads ranks and scores from Redis, then retrieves display information such as product and brand names from MySQL.

Another benefit is freshness. Scores change as soon as events are consumed, so user actions are reflected quickly. A batch-only design introduces at least the scheduling delay; here, Kafka consumer lag accounts for most of the delay.

End-of-day carry-over

Starting every product at zero each day would feel abrupt. Products that were popular yesterday shouldn’t necessarily disappear at midnight.

I planned a carry-over at 23:50 each day, using that day’s Top 100 products to seed the next day’s scores.

Read the Top 100 from ranking:all:{D}
Multiply each final score by 0.1
Apply to ranking:metric:carry:{D+1}
Also apply to ranking:all:{D+1}

The Top 100 limit controls Redis memory usage. Carrying every product forward would become expensive as product counts and daily keys accumulate.

Keys also have a TTL. Together, expiry and the carry-over limit keep Redis from becoming an indefinite historical store.

Limitations of the first design

The Redis design is simple and fast for daily real-time rankings. Looking at it from an operational perspective reveals several limitations.

1. Can Redis be the Source of Truth?

This was my biggest concern.

Redis works well for serving ranking data, but this design needs more support for preserving the source information. TTL expiry removes data. After an outage or operational mistake, we need enough evidence to reconstruct rankings, and a Redis-centered design alone doesn’t provide that.

Retaining Kafka topics and replaying events is an option. But replaying all events just to recalculate one historical period can be costly. If the event schema or consumer logic has changed, reproducing the original result may also be difficult.

2. Changing weights and recalculating scores

The first design’s separate metric ZSETs allow recalculation while the daily data remains in Redis.

After the TTL expires, that option disappears. A request a month later to recalculate last week’s rankings with today’s weights cannot rely on the remaining Redis data alone.

Runtime weight changes make the distinction between metrics and scores important. A score is the result of a policy; the metrics describe what happened.

3. Rankings across different periods

Date-based keys look sufficient for daily rankings. Hourly, weekly, monthly, and yearly rankings make the key strategy more complicated.

ranking:all:daily:20260717
ranking:all:hourly:2026071713
ranking:all:weekly:2026W29
ranking:all:monthly:202607

We could update every period’s keys when consuming each event. But then a single event modifies multiple keys, and weight changes require recalculating more sets of scores.

At that point, retaining source metrics elsewhere and publishing each period’s Top N to Redis becomes a more natural design.

4. Should every product live in Redis?

The memory question also becomes more important as the catalog grows.

Storing 100,000 products is something we can test readily. At one million or ten million products, multiplied across daily keys, Redis memory cost becomes harder to ignore.

Most ranking API requests need only the Top N. Keeping those results in Redis and the complete metrics elsewhere gives each store a clearer role.

Revised design: RDB Metric SOT + Redis Top N

To address those limits, I explored storing source metrics in an RDB and serving only query-ready Top N results from Redis.

Redis changes roles in this design. In the first version, it was effectively the Source of Truth for real-time rankings. Here, it is a read model for fast queries.

Source metrics live in an RDB such as MySQL.

ranking_daily_metric
- metric_date
- product_id
- view_count
- like_count
- sales_amount

Weights are deliberately left out of those records. Views, likes, and sales amounts describe recorded activity; weights are policy, and policy can change. Storing metrics before weights are applied makes recalculation easier.

Event consumption

The event pipeline stays largely the same. User actions reach Kafka, and RankingMetricConsumer consumes them. Instead of incrementing Redis scores directly, it upserts metric rows in the RDB.

PRODUCT_VIEWED -> view_count + 1
PRODUCT_LIKED -> like_count + 1
PRODUCT_UNLIKED -> like_count - 1
PAYMENT_SUCCEEDED -> sales_amount + price * quantity

Rankings can now be rebuilt from RDB metrics even if Redis is empty.

Weekly rankings can be computed by summing daily metrics over the required period, and monthly rankings work the same way. Neither requires replaying every original event.

Score calculation

A separate batch or scheduler calculates scores. For example, it can read recent metrics every five minutes and apply the current weights.

score = carry
 + view_count * currentViewWeight
 + like_count * currentLikeWeight
 + ln(1 + sales_amount) * currentSalesWeight

It then loads only the Top N products into a Redis ZSET.

ranking:top:daily:20260717

Redis contains the results the API needs rather than the entire catalog. It serves as the fast serving layer, while the source data remains elsewhere.

What this design improves

The biggest improvement is recoverability. If Redis data is lost, the Top N can be rebuilt from RDB metrics. If incorrect weights are deployed, the same metrics can be used to calculate corrected scores.

The second improvement is support for different ranking periods. With daily metrics, weekly, monthly, and yearly rankings become period aggregation problems. At larger scale, an RDB alone may not be enough; an OLAP store or separate aggregate tables could be needed. Retaining the source metrics leaves those options open.

Third, Redis memory usage becomes easier to control. Only the Top N needed for queries lives there. Full product metrics remain in the RDB.

What it costs

This design isn’t automatically better in every respect.

Rankings become less immediate. A five-minute calculation schedule can introduce roughly five minutes of update delay.

The system also becomes more involved. It needs metric tables, upsert logic, score calculation batches, batch failure recovery, and Redis loading logic. There is more to manage than a direct ZINCRBY on a ZSET.

RDB write load matters, too. Every user action can lead to a metric upsert. At higher traffic volumes, buffering, batch inserts, time-bucket aggregation, Kafka Streams, or an OLAP store may become worth considering.

Comparing the designs

Perspective	Real-time Redis rankings	RDB Metric SOT + Redis Top N
Priority	Immediate updates	Recovery and recalculation
Redis role	Real-time ranking store	Query read model
Source metrics	Stored in Redis keys	Persisted in the RDB
Weight changes	Recalculate only periods still in Redis	Recalculate from retained RDB metrics
Multiple periods	More keys add complexity	Extend through metric aggregation
Memory usage	Grows when all products are loaded	Controlled by loading only Top N
Implementation complexity	Relatively simple	Requires batch and recovery policies
Update delay	Low	Depends on the batch interval

The first design is a good starting point for fast daily rankings. User actions are reflected almost immediately, and the API read path is simple.

As recovery, recalculation, and rankings across longer periods become operational requirements, the RDB Metric SOT design becomes more compelling.

How should we choose?

This exercise made me realize that the first question shouldn’t be which database to use. More useful questions are:

How quickly must this ranking reflect new activity?
Can we tolerate losing the ranking data?
Do historical rankings need to be recalculated?
Could the weight policy change frequently?
Do all products need to remain in the ranking dataset?
Will rankings stay daily, or expand to weekly and monthly periods?

If the answers prioritize freshness, a Redis-centered design is simple and fast. If recovery, auditing, recalculation, and broader time periods matter, the system needs to retain source metrics.

Evolving the design

The real-time Redis design initially seemed sufficient. Daily rankings needed to respond quickly to user behavior, and Sorted Sets supported both Top N queries and individual product ranks well.

I placed several limits on that design:

Use date-specific keys.
Give keys a TTL.
Carry over only the Top 100 products.
Keep metric ZSETs separate so weights can be recalculated for retained daily data.
Track processed events to avoid duplicate updates.

These choices make it a starting point that favors freshness and simplicity. Once historical recovery or weekly and monthly rankings enter the requirements, evolving toward RDB Metric SOT + Redis Top N makes more sense.

Closing thoughts

Designing rankings kept bringing me back to questions beyond sorting: which actions count as strong signals, how long to retain them, whether scores must be recalculated when policy changes, and whether an empty ranking after Redis failure is acceptable.

I began by focusing on how quickly Redis Sorted Sets could provide rankings. As the design grew, deciding what to preserve as source data became more important than deciding what to put in Redis.

The first design is a starting point for real-time daily rankings. RDB Metric SOT + Redis Top N is a possible next step as operational requirements grow.

I don’t think a good design has to implement every future requirement from the start. But I do want to be able to explain the limits of today’s choice and how it could evolve when those limits matter.

Handling Order Surges: Designing a Redis Waiting Queue

Fri, 10 Jul 2026 16:59:39 +0900

TL;DR

Instead of sending every request straight to the order API, I first placed users in a Redis Sorted Set.

A scheduler removes up to 50 users from the queue every second and issues entry tokens valid for five minutes. Users poll their position until they receive a token, and the order API accepts only requests with a valid X-Entry-Token.

After an order commits successfully, a local event listener receives OrderEvent.Created and deletes the token. If the order fails, the token remains so the user can try again.

This is an initial design for controlling admission rate, rather than a complete production waiting queue. Atomic queue entry, recovery during token issuance, global throughput across instances, and polling load still need more work.

Overview

Goals:
- Keep a sudden burst of order requests from reaching the order database all at once.
- Let users check their queue position and estimated wait time.
- Issue entry tokens to a limited number of users who can then call the order API.
- Remove entry tokens only after a successful order transaction.
- Keep the waiting queue and order domains independent of Redis implementation details.
Settings used in this implementation:
- Scheduler fixed delay: 1 second
- Scheduler batch size: 50 users
- Entry token TTL: 300 seconds
- Rank: zero-based, using the Redis ZRANK result directly

Why put a queue in front of the order API?

A modest rise in order traffic may be handled by scaling out application servers or tuning the database connection pool.

A sharp burst at the start of an event is different. Even with more application instances, requests converge on the same database to lock inventory and coupon rows and save orders. Accepting more requests at the application tier can make database connection demand and lock waits grow even faster.

The queue’s purpose is to admit requests at a rate the downstream system can handle, while other users wait outside that processing path.

I chose not to store order request payloads in the server-side queue. The queue contains only memberId; once admitted, the user sends the original order request again.

This avoids managing the state and retry policy of queued order payloads on the server. The client instead needs to poll its position and call the order API after reaching READY.

Overall architecture

The flow has three parts:

Register users in a Redis ZSET and expose their current status.
Let the scheduler remove users from the front and issue entry tokens.
Validate tokens at the order API and delete them through a local event after the order commits.

The layers have distinct responsibilities:

Layer	Responsibility
Interface	Waiting queue and order APIs, plus the order completion event listener
Application	User authentication, queue status assembly, token issuance, and order admission validation
Domain / Port	The `WaitingQueuePosition` state model and Repository interfaces that abstract Redis
Infrastructure	Repository port implementations using Spring Data Redis
Redis	A ZSET for waiting order and a String entry token for each admitted user

1. Representing queue order with a Redis Sorted Set

The queue needs to answer three main questions:

Is the user in the queue?
What is their current position?
How many users are waiting in total?

A Redis Sorted Set can represent all three.

key : queue:waiting
member : memberId
score : enteredAt

Because memberId is unique within the ZSET, adding the same user repeatedly doesn’t create duplicate members. Using enteredAt as the score places earlier users ahead of later ones. ZRANK returns their position, and ZPOPMIN removes users from the front.

I use the ZRANK value directly, so the first user’s rank is 0. Keeping both the internal model and API response zero-based avoids +1 and -1 conversions at every boundary.

Preserve the position on repeated entry

A waiting user may refresh the page or call the entry API again. Overwriting the score with the current time would send them to the back.

The current implementation checks for an existing score and adds only users who aren’t already registered.

override fun enterIfAbsent(memberId: Long, score: Double) {
 val member = memberId.toString()
 if (redisTemplate.opsForZSet().score(WAITING_QUEUE_KEY, member) == null) {
 redisTemplate.opsForZSet().add(WAITING_QUEUE_KEY, member, score)
 }
}

This preserves the score and rank across sequential repeated calls.

There is an important limitation: ZSCORE and ZADD are separate commands. Two simultaneous first-entry requests for the same user can both see no score and then write different scores. Strict idempotency requires a single atomic Redis operation such as ZADD NX or addIfAbsent.

2. One response model for waiting status

After entering, clients poll the same position API. It returns one of three states:

WAITING: the user is in the ZSET and has no entry token yet.
READY: the user has an entry token and can call the order API.
NOT_ENTERED: the user is neither in the queue nor holding a valid entry token.

Status checks look for the entry token first. The scheduler removes users from the ZSET before issuing tokens, so a READY user is no longer in the ZSET. Checking rank first could incorrectly classify an admitted user as NOT_ENTERED.

stateDiagram-v2
 [*] --> NOT_ENTERED
 NOT_ENTERED --> WAITING: enter() / register in queue
 WAITING --> WAITING: position polling
 WAITING --> READY: scheduler / issue token
 READY --> READY: order rollback / retain token
 READY --> NOT_ENTERED: order commit / delete token
 READY --> NOT_ENTERED: TTL expires

WaitingQueuePosition uses the retrieved rank and total waiting count to calculate these response values:

status
rank
currentTotalWaitingCount
estimatedWaitSeconds
pollingIntervalSeconds
entryToken

The estimated wait is the current rank divided by an assumed throughput of 50 users per second. The polling interval is one second with fewer than 100 users ahead, three seconds with fewer than 1,000, and five seconds otherwise.

Users near admission receive faster updates, while users further back make fewer Redis queries. Since the throughput assumption is fixed, this is only a rough estimate; it doesn’t reflect actual order processing speed.

3. Controlling admission rate with a scheduler

Sending all queued users to the order API at once would defeat the purpose of the queue.

WaitingQueueScheduler calls issueNextEntries() every second. The service uses ZPOPMIN to remove up to 50 users with the lowest scores and issues a token to each.

fun issueNextEntries(batchSize: Long): List<String> {
 return waitingQueueRepository.popNext(batchSize)
 .mapNotNull { memberId ->
 val token = generateToken()
 entryTokenRepository.issue(memberId, token, properties.entryTokenTtl)
 entryTokenRepository.find(memberId)
 }
}

Each token is a URL-safe Base64 encoding of 32 bytes generated by SecureRandom.

key : queue:entry-token:{memberId}
value : generated token
TTL : 300 seconds

The application doesn’t return the generated token directly. It stores it in Redis and reads it back, so a token that wasn’t stored isn’t treated as a valid admission credential.

The TTL serves two purposes. It prevents a token from granting indefinite access to the order API, and it eventually cleans up tokens even if deletion after order completion fails.

A very short TTL could expire while a user is preparing an order. A very long TTL leaves users eligible to enter long after they have stopped trying. The current 300-second value is the assignment’s default policy; a production value should be based on measured user behavior and target throughput.

4. Requiring an entry token at the order API

Order requests include an X-Entry-Token header.

After authentication, OrderFacade.placeOrder() compares the request token with the one stored in Redis. A missing, mismatched, or expired token results in 401 Unauthorized before order processing begins.

I put this validation in the application layer because eligibility to place an order is a precondition of the use case, beyond simply validating an HTTP header’s format.

This is a fail-closed design: when Redis doesn’t respond, orders are blocked. I chose to stop accepting orders instead of letting traffic bypass the queue and overwhelm downstream systems. That protects the server, but makes a Redis outage an order outage as well.

5. Deleting tokens outside the order transaction

I initially considered deleting the token directly inside the order creation method.

That would mix an external Redis operation into the database transaction flow. Deleting the token before commit is also problematic: if the order rolls back, the user loses admission even though the order failed.

The order flow already publishes OrderEvent.Created on success, so I moved token deletion into a listener that receives this local event at AFTER_COMMIT.

@TransactionalEventListener(phase = TransactionPhase.AFTER_COMMIT)
fun handle(event: OrderEvent.Created) {
 waitingQueueService.deleteEntryToken(event.memberId)
}

This gives us two useful properties:

A rolled-back order leaves the token available for another attempt.
A token cleanup failure cannot roll back an already committed order.

A local event is not a durable message, however. If the process exits just after commit, or Redis deletion fails, the listener has no automatic recovery. The TTL provides eventual cleanup for now. Immediate cleanup would require a retryable event record or a separate cleanup job.

AFTER_COMMIT also does not automatically mean asynchronous execution or exception isolation. The current listener runs in the same call flow as the order request. If a Redis deletion exception propagates, the HTTP response can fail even though the order has committed. Production handling needs an explicit policy for logging and alerting on those exceptions, alongside retryable cleanup work.

Technical decisions

Design area	Choice	Reason
Waiting order	Redis Sorted Set	Unique members, score ordering, rank, and total count in one structure
ZSET member	`memberId`	One waiting entry per user
ZSET score	Entry timestamp in milliseconds	Give earlier arrivals priority
Admission control	Fixed-delay scheduler + batch size	Limit the rate at which users reach downstream processing
Admission credential	Per-user Redis String token + TTL	Separate waiting from readiness and expire old credentials automatically
Status updates	Client polling	Expose positions through a simple HTTP API without a separate push channel
Order validation	Start of `OrderFacade`	Check admission before expensive order processing
Token cleanup	`AFTER_COMMIT` listener for `OrderEvent.Created`	Clean up only successful orders and separate deletion from order rollback

Trade-offs

Admission rate is controlled, but concurrent orders are not strictly bounded

Issuing 50 tokens per second doesn’t guarantee that no more than 50 orders run at once.

Tokens remain valid for 300 seconds. Users admitted across several seconds can wait and then submit orders at the same moment. This design controls the token issuance rate, not actual in-flight order concurrency.

A strict downstream concurrency limit would need active slots, token claims, a semaphore, or another control. Another option is to admit users based on actual order completion rate.

Polling is simple, but creates read traffic

HTTP polling is easy to implement on both sides and doesn’t require long-lived connections. But more waiting users mean more repeated GET token, ZRANK, and ZCARD calls. Varying the polling interval by rank reduces that load.

At larger scale, I would consider client-side jitter to spread requests out, longer polling intervals, Redis read replicas rather than CDN caching for these reads, or SSE-based push.

Separate cleanup does not guarantee immediate cleanup

An AFTER_COMMIT listener reduces the responsibilities inside the order transaction. Its failures happen after the order succeeds, though, so the order cannot be rolled back. A local event also leaves no retry record.

The TTL eventually resolves the leftover-token state, but the token can remain valid until it expires.

A Redis outage stops orders

Fail-closed behavior protects the database from requests bypassing the queue, while making Redis a required dependency of the entire order flow. Production design needs replication, Sentinel or Cluster, persistence, and failover policies as well.

Remaining limitations and work beyond the assignment

1. Concurrent entry by the same user must be atomic

ZSCORE followed by ZADD is a check-then-act sequence. I verified concurrent entry by eight distinct users and sequential repeated entry by the same user. That does not establish atomicity for simultaneous first-entry requests from one user.

This should use the single ZADD NX command.

2. Users can be lost between ZPOPMIN and token storage

The scheduler removes a user from the ZSET before saving the token. If the process exits or the Redis write fails between those operations, the user has neither a queue entry nor a token and becomes NOT_ENTERED.

Reading the token back after storage cannot recover a user who has already been popped.

A production design could atomically move users into a processing ZSET, then acknowledge them after token issuance succeeds. A recovery job could return users without an acknowledgment to the waiting ZSET after a timeout.

3. Batch size is not a global limit across application instances

If every instance runs the scheduler, each can pop 50 users per second. ZPOPMIN prevents duplicate removal of the same user, but four instances can issue up to 200 tokens per second in total.

Using batch size as a global throughput limit requires scheduler leader election, a distributed lock, a dedicated worker, or a Redis-based global rate limiter.

4. The token grants temporary admission, not exactly one order

Token deletion happens after order commit. Two concurrent requests from the same user with the same token can both pass validation.

If one token must authorize only one order, validation and claiming it must be atomic. A simple GETDEL at order start also removes the token when the order later rolls back. A more complete design needs states such as READY → CLAIMED → CONSUMED, plus a release policy on rollback. Order-level idempotency keys deserve separate consideration, too.

5. Estimated wait time doesn’t reflect real throughput

The current formula is rank / 50. It matches the scheduler setting but ignores database latency, order success rate, users who receive tokens without ordering, and outages.

A moving average of recent token issuance and order completion rates, together with batch-size adjustments based on operational metrics, would provide a more realistic estimate.

6. Arrivals within the same millisecond are not strictly FIFO

Scores use application timestamps in milliseconds. Multiple users can arrive in the same millisecond, and clock differences across application servers can change score order relative to actual arrival order.

For equal scores, Redis ZSET orders members lexicographically, which can also differ from arrival order. Strict FIFO would require a design using Redis TIME with a sequence, or a separate incrementing value in the score.

What I verified

Using Testcontainers Redis and API E2E tests, I checked:

First entry returns rank 0 and the total waiting count.
Sequential repeated entry preserves the user’s rank.
Concurrent entry by distinct users assigns unique ranks.
Responses represent WAITING, READY, and NOT_ENTERED.
Tokens are unavailable after their TTL expires.
One scheduler run issues no more than the batch size, even with more users waiting.
Orders without an entry token are rejected.
A successful order commit deletes the entry token.

These tests verify functional contracts. They don’t establish maximum capacity or the right batch size. To choose production settings, I would use a tool such as k6 to generate entry bursts and position polling together, while observing application latency, Redis command throughput, CPU, memory, and connection counts.

Alternatives considered

Option	Benefits	Costs
Delete the token inside the order transaction	The full flow is visible in the order code	Redis cleanup becomes part of the transaction’s responsibilities, and rollback handling becomes more complicated
Selected: delete through an `AFTER_COMMIT` local event	Clean up successful orders and separate post-processing from the transaction	Listener failures aren’t automatically recovered; tokens can remain until TTL expiry

The central decision was that token deletion should not determine whether an order succeeds.

Once an order has committed, preserving that success and cleaning up the token separately makes more sense than presenting a failure because cleanup failed.

The local event alone doesn’t provide that reliability, though. It separates responsibilities, while failure recovery still relies on the TTL. A cleaner structure and a more reliable production system are separate outcomes.

Closing thoughts

At first, I thought adding users to a Redis ZSET and returning their rank would complete the queue implementation.

Most of the difficult questions turned out to concern when a user becomes eligible to order, when that eligibility ends, and which state they should return to after a failure.

In this design, the ZSET represents waiting and the TTL token represents readiness. The order API checks the token, and an event after order commit triggers cleanup. This made the boundary between queue responsibilities and the order transaction clearer.

It also exposed gaps: atomic registration, recovery after pop, global throughput across instances, one-time token use, and wait estimates based on actual throughput. The assignment didn’t force all of these issues into view, but production use would require addressing them.

A waiting queue is an admission control system. It needs to move users at a pace the system can handle and preserve their state transitions even when something fails.

Why I Chose Pessimistic Locking for Order Consistency

Fri, 12 Jun 2026 05:50:00 +0900

TL;DR

There were two failures I wanted the order flow to prevent: two successful orders using the same coupon, and more successful orders than available stock.

For this flow, I chose to acquire locks up front and serialize conflicting work with pessimistic locking, rather than detect conflicts through optimistic locking.

Overview

Goals:
- Save the order, deduct inventory, and consume the coupon in one transaction.
- Allow an issued coupon to be used only once, even under concurrent requests.
- Allow concurrent orders for a product to succeed only up to the available stock quantity.
- Avoid partial changes to orders, inventory, or coupons when a request fails.

The problem

A transaction guarantees atomicity within a request. It doesn’t automatically solve every problem caused by multiple requests reading and modifying the same data concurrently.

Two orders using the same coupon can both read AVAILABLE. If ten users order a product with five units left, more than five orders could succeed.

I wanted to prevent these outcomes when the order was created rather than detect and correct them afterward.

Order processing flow

Order creation follows this flow:

flowchart TD
 A["Order request"] --> B["Authenticate user"]
 B --> C["Sort requested product IDs"]
 C --> D["Read coupon issue row with pessimistic lock"]
 C --> E["Read inventory rows with pessimistic locks"]
 D --> F["Load products / brands"]
 E --> F
 F --> G["Validate domain rules"]
 G --> H{"Validation passed?"}
 H -- "No" --> R["Roll back transaction"]
 H -- "Yes" --> I["Deduct inventory"]
 I --> J["Mark coupon USED"]
 J --> K["Save order"]
 K --> L["Commit transaction"]

The key is to lock the coupon and inventory first, then complete validation and updates within the same transaction. If validation fails, no order is saved and no coupon or inventory changes are committed.

Technical decisions

Design area	Choice	Rationale
Order transaction boundary	`OrderFacade.placeOrder`	Keep authentication, inventory, coupon use, and order persistence within one atomic use case
Coupon concurrency control	Pessimistic lock on the `CouponIssue` row	Serialize validation and the transition to `USED` so an issued coupon can be used only once
Inventory concurrency control	Pessimistic lock on the `Inventory` row	Prevent overselling and make deduction results predictable
Orders with multiple products	Sort by `productId` before acquiring locks	Reduce deadlock risk by using a consistent lock acquisition order
Like count	Pessimistic lock on the `ProductStat` row	Prevent a Lost Update to `likeCount` during concurrent like and unlike requests
Coupon terms	Snapshot stored in `CouponIssue`	Preserve the discount terms promised at issuance when the coupon is used later

Why pessimistic locking?

Conflicts involving coupons and inventory have a high cost. Duplicate coupon use directly affects money, and overselling produces successful orders for stock that no longer exists.

Optimistic locking detects a conflict after concurrent work has taken place. That can be the right choice, but here it would also require decisions about retries, failures, and the response presented to the user.

Pessimistic locking serializes work on the same CouponIssue or Inventory row from the start. Requests may wait, but only one request at a time validates and changes the locked data, making the outcome easier to reason about.

For this implementation, preserving states that must never be violated took priority over throughput.

Detailed design

1. Lock CouponIssue for coupon use

The one-time resource is the issued coupon, not the coupon template.

When an order request contains couponId, I load the CouponIssue row with PESSIMISTIC_WRITE. The domain then validates ownership, usage status, expiration, and the minimum order amount before changing the status to USED.

flowchart LR
 A["CouponIssueEntity
SELECT FOR UPDATE"] --> B["Convert to CouponIssue domain model"]
 B --> C["Domain.use()
Validate + mark USED"]
 C --> D["Reload entity"]
 D --> E["entity.update(domain)"]
 E --> F["Flush at commit"]

 subgraph TX["Same database transaction"]
 A
 B
 C
 D
 E
 F
 end

Pessimistic locking still works when the domain model and JPA entity are separate. The lock is associated with the database row and transaction, not the domain object.

Changing the domain object doesn’t trigger dirty checking, however. Its values must be copied back to the entity before persistence.

2. Sort productId before locking inventory

An order can contain multiple products, so it may need locks on several Inventory rows.

Different lock acquisition orders increase the risk of deadlock. If request A locks product 1 and then product 2 while request B locks product 2 and then product 1, each can end up waiting for the other’s lock.

I therefore remove duplicate product IDs and sort them before loading the rows. This doesn’t eliminate every possible deadlock, but it provides a basic safeguard.

flowchart TD
 A["Order product IDs
3, 1, 2, 1"] --> B["Remove duplicates
3, 1, 2"]
 B --> C["Sort
1, 2, 3"]
 C --> D["Lock Inventory rows
in order: 1 -> 2 -> 3"]
 D --> E["Validate inventory"]
 E --> F["Deduct inventory"]

3. Snapshot coupon terms at issuance

If CouponIssue only references Coupon and doesn’t hold its own discount terms, those terms can change between issuance and use.

A user might receive a 10% coupon, only to get 5% off after someone edits the template.

I store type, discountValue, minOrderAmount, and expiredAt as a snapshot in CouponIssue. The extra columns are a cost I accepted to preserve what was promised to the user.

flowchart LR
 A["Coupon template
10% discount"] --> B["Issue CouponIssue"]
 B --> C["Snapshot
type / discountValue / minOrderAmount / expiredAt"]
 A --> D["Template later edited or deleted"]
 C --> E["Calculate order discount
from the CouponIssue snapshot"]

Alternatives considered

Option	Pros	Cons
A. Optimistic locking	No lock waiting when conflicts are rare	Requires a retry/failure policy after conflicts and complicates order responses
B. Pessimistic locking	Serializes validation and updates, making duplicate use and excessive deductions easier to reason about	Busy rows cause longer waits; deadlocks need consideration
C. Queue-based serial processing	Straightforward sequential processing for hot keys	Requires redesigning order states and responses around an asynchronous flow
Selected: B	Clearest consistency checks and failure rules for the current requirements	Requires care with lock duration and query order

Why I chose B:

A successful order appears to the user as an immediate, confirmed outcome. If stock is insufficient or a coupon has already been used, I would rather reject the request up front than show success and cancel it later.

That led me to lock the contested resources before validation. Optimistic locking has clear benefits, but conflict handling would become a central source of complexity in this flow. Pessimistic locking trades some performance for simpler success and failure rules.

Open questions and trade-offs

Experimenting with optimistic locking also made the cost of separating domain models from JPA entities more apparent.

@Version and dirty checking fit most naturally when working directly with entities. Exposing entities to the application layer makes JPA features convenient to use, but weakens the layer boundaries. Keeping entities inside infrastructure makes the Mapper and Repository implementations more complicated.

I don’t take this to mean that pessimistic locking is always the right answer. Preventing duplicate coupon use and excessive inventory deductions was the priority for this order flow, and pessimistic locking addressed that priority directly.

Deadlocks remain a concern. Sorting by productId reduces the risk by aligning lock acquisition order, but it isn’t a complete solution. Still, a consistent order is a basic precaution whenever a flow locks multiple rows.

Separating Domain Models from JPA Entities

Fri, 29 May 2026 12:43:19 +0900

TL;DR

I separated domain models from database entities to keep business rules in the domain and isolate JPA mappings and persistence concerns in the infrastructure layer.

Core models such as User, Product, and Order can now express domain rules without JPA annotations. Repository implementations use Mappers to convert between those models and database entities.

The separation also raised questions: where DTO-like objects should live, what Mappers should own, how to reload entities for updates, and where read query projections belong.

Overview

Goals:
- Separate the domain rules and persistence mappings previously handled by a single JPA entity.
- Let domain models express business rules and database entities handle table mappings and persistence.
- Let the Application Layer coordinate domain objects while the Infrastructure Layer stores and retrieves data through JPA.
Main design priorities:
- Remove direct JPA dependencies from the Domain Layer.
- Keep Repository interfaces in the Domain Layer and implementations in the Infrastructure Layer.
- Use Mappers to convert between database entities and domain models.
- Express domain rules through methods and constructor validation rather than entity annotations.

Why separate them?

The original Member implementation had a service layer that called repositories directly and also handled business logic. That is quick to build for small features, but several problems emerge as the domain grows.

First, the JPA entity takes on too many responsibilities. It already uses annotations such as Column, Entity, Table, and OneToMany to describe table mappings. Adding business rules means the same object must understand both the database structure and the domain.

Second, testing becomes harder. When domain logic is built around JPA entities, even simple rule checks can make us think about the persistence context and JPA behavior. A plain Kotlin domain object lets us test rules through its constructor and methods without a repository.

Third, names and responsibilities become mixed. This project called the user domain User, but used a database table named member. Calling the JPA class UserEntity made imports and concepts feel inconsistent. I kept User in the domain and used database-oriented names such as MemberEntity, MemberMapper, and MemberRepositoryImpl in infrastructure.

Technical decisions

Design area	Choice	Rationale
Domain models and database entities	Separate them	Separate domain rules from JPA mapping responsibilities
Repository placement	Interface in Domain, implementation in Infrastructure	Avoid coupling the application to a concrete JPA implementation
Conversion	Separate Mapper	Keep both conversion directions together instead of adding methods such as `toDomain` to entities
Entity names	`MemberEntity`, `ProductEntity`, `OrderEntity`	Make their role as table-mapped persistence models explicit
Domain names	`User`, `Product`, `Order`	Express the business concepts directly
Query optimization	Projections for some list queries	Converting every result to a domain object can hurt sorting and pagination performance

How I applied it

1. Separating User from MemberEntity

The domain model has no JPA annotations. User expresses the business rules for a member.

class User(
 val id: Long = 0L,
 loginId: String,
 password: String,
 name: String,
 birthDate: LocalDate,
 email: String,
) {
 var loginId: String = loginId
 private set

 var password: String = password
 private set

 var name: String = name
 private set

 var birthDate: LocalDate = birthDate
 private set

 var email: String = email
 private set

 init {
 if (!loginId.matches(LOGIN_ID_REGEX)) {
 throw CoreException(ErrorType.BAD_REQUEST, "LoginId must contain only letters and numbers.")
 }
 if (!name.matches(NAME_REGEX)) {
 throw CoreException(ErrorType.BAD_REQUEST, "Name cannot contain special characters or numbers.")
 }
 if (!email.matches(EMAIL_REGEX)) {
 throw CoreException(ErrorType.BAD_REQUEST, "Email cannot contain special characters or numbers.")
 }
 if (birthDate.isAfter(LocalDate.now())) {
 throw CoreException(ErrorType.BAD_REQUEST, "Birthdate must be before now.")
 }
 }

 fun updatePassword(encodedPassword: String) {
 this.password = encodedPassword
 }
}

The database entity lives in infrastructure and maps to the member table.

@Entity
@Table(name = "member")
class MemberEntity(
 @Column(nullable = false, unique = true)
 var loginId: String,

 @Column(nullable = false)
 var password: String,

 @Column(nullable = false)
 var name: String,

 @Column(nullable = false)
 var birthDate: LocalDate,

 @Column(nullable = false)
 var email: String,
) : BaseEntity() {
 fun update(user: User) {
 loginId = user.loginId
 password = user.password
 name = user.name
 birthDate = user.birthDate
 email = user.email
 }
}

Although User and MemberEntity hold the same data, they have different responsibilities. User represents the business concept of a member. MemberEntity is the persistence model used to store that information in the member table.

2. Moving conversion into a Mapper

Separate models need conversion code. I introduced a dedicated Mapper instead of putting toDomain inside the entity.

object MemberMapper {
 fun toDomain(member: MemberEntity): User {
 return User(
 id = member.id,
 loginId = member.loginId,
 password = member.password,
 name = member.name,
 birthDate = member.birthDate,
 email = member.email,
 )
 }

 fun toEntity(user: User): MemberEntity {
 return MemberEntity(
 loginId = user.loginId,
 password = user.password,
 name = user.name,
 birthDate = user.birthDate,
 email = user.email,
 )
 }
}

The goal was to reduce how much the entity needed to know about the domain.

Some dependencies remain. For example, MemberEntity.update(user: User) still accepts a domain object. During an update, I load a JPA managed entity and copy the domain values onto it.

A stricter separation could make update accept primitive values or a command instead. But that can add duplication as the number of fields grows. I chose a practical separation rather than complete isolation.

3. Separating Product from ProductEntity

Product owns product rules. A product name cannot be empty, its price cannot be negative, and deletion is expressed as a change to its state.

class Product(
 val id: Long = 0L,
 val brandId: Long,
 name: String,
 price: Long,
 description: String,
 imageUrl: String,
 isDeleted: Boolean = false,
) {
 var name: String = name
 private set

 var price: Long = price
 private set

 var description: String = description
 private set

 var imageUrl: String = imageUrl
 private set

 var isDeleted: Boolean = isDeleted
 private set

 init {
 validate(
 brandId = brandId,
 name = name,
 price = price,
 description = description,
 imageUrl = imageUrl,
 )
 }

 fun update(
 name: String,
 price: Long,
 description: String,
 imageUrl: String,
 ) {
 validate(
 brandId = brandId,
 name = name,
 price = price,
 description = description,
 imageUrl = imageUrl,
 )

 this.name = name
 this.price = price
 this.description = description
 this.imageUrl = imageUrl
 }

 fun delete() {
 isDeleted = true
 }
}

ProductEntity maps to the product table and contains the JPA annotations and database constraints.

@Entity
@SQLRestriction("is_deleted = false")
@Table(
 name = "product",
 uniqueConstraints = [
 UniqueConstraint(
 name = "uk_product_brand_id_name",
 columnNames = ["brand_id", "name"],
 ),
 ],
)
class ProductEntity(
 @Column(name = "brand_id", nullable = false)
 var brandId: Long,

 @Column(nullable = false)
 var name: String,

 @Column(nullable = false)
 var price: Long,

 @Column(nullable = false)
 var description: String,

 @Column(nullable = false)
 var imageUrl: String,

 @Column(nullable = false)
 var isDeleted: Boolean = false,
) : BaseEntity() {
 fun update(domain: Product) {
 brandId = domain.brandId
 name = domain.name
 price = domain.price
 description = domain.description
 imageUrl = domain.imageUrl
 isDeleted = domain.isDeleted
 }
}

This separation lets infrastructure handle the soft delete query policy while Product expresses the domain action of deleting a product.

There is a trade-off, though. SQLRestriction automatically excludes deleted data from ordinary queries, so the application layer doesn’t need to check isDeleted every time. Features such as administrative auditing or restoration need a separate query path that can include deleted records.

4. Separating the Repository interface from its implementation

The Domain Layer contains only the Repository interface.

interface ProductRepository {
 fun findById(productId: Long): Product?

 fun findAllByIds(productIds: Collection<Long>): List<Product>

 fun save(product: Product): Product

 fun update(product: Product): Product
}

The Infrastructure Layer contains the implementation that uses the JPA repository.

@Component
class ProductRepositoryImpl(
 private val productJpaRepository: ProductJpaRepository,
) : ProductRepository {
 override fun findById(productId: Long): Product? {
 return productJpaRepository.findByIdOrNull(productId)
 ?.let(ProductMapper::toDomain)
 }

 override fun save(product: Product): Product {
 return productJpaRepository.save(ProductMapper.toEntity(product))
 .let(ProductMapper::toDomain)
 }

 override fun update(product: Product): Product {
 val entity = productJpaRepository.findByIdOrNull(product.id)
 ?.also { it.update(product) }
 ?: throw CoreException(ErrorType.NOT_FOUND, "Product not found.")

 return productJpaRepository.save(entity)
 .let(ProductMapper::toDomain)
 }
}

The Application Service depends only on ProductRepository. Tests can supply a fake repository to check domain behavior, while production uses the JPA implementation.

Troubleshooting

Where the complexity appeared

There were moments when separating the models actually made the code more complicated. I spent time thinking about:

Naming a User domain backed by a member table.
The apparent duplication of fields between domain objects and entities.
Where Mappers should live.
Whether an update should reload the JPA entity.
Whether list queries should always return domain models.
Whether DTO-like objects such as ProductSummary belong in the domain.

Why these questions arose

One source of confusion is that “Entity” has two meanings. In DDD, an Entity is a domain object with an identity. A JPA entity is a persistence object mapped to a database row. Because both are called entities, it is easy to assume they must be the same object.

For this project, I saw different reasons for them to change:

A domain model changes when business rules change.
A database entity changes when the table structure or JPA mapping changes.

Another source of complexity is the difference between queries and commands. For flows such as creating an order or updating a product, converting to a domain model makes sense because domain rules matter. For read queries where sorting, pagination, and projections matter most, that conversion can be unnecessary overhead.

The product list needed data from Product, Brand, and ProductStat, along with likes_desc sorting. Fetching each domain separately and merging the results in memory could break pagination accuracy. I used a QueryDSL projection for that query.

What I changed

1. Make responsibilities visible in names

I kept business names such as User, Product, and Order in the domain. Infrastructure uses MemberEntity, ProductEntity, and OrderEntity to make the persistence role explicit.

For User, the table name member informed the infrastructure name Member. This made the imports easier to understand:

domain.user.User
infrastructure.member.MemberEntity
infrastructure.member.MemberMapper
infrastructure.member.MemberRepositoryImpl

2. Keep Mappers in Infrastructure

A Mapper needs to know about the database entity, so it belongs in infrastructure. Making the Domain Layer aware of JPA entities would weaken the separation.

The structure currently looks like this:

domain/user/User
domain/user/UserRepository

infrastructure/member/MemberEntity
infrastructure/member/MemberMapper
infrastructure/member/MemberRepositoryImpl

3. Load a managed entity before applying updates

Creating a new JPA entity from a modified domain object and calling save can lead to an insert instead of an update, or make ID handling awkward.

For updates, I load the existing entity and apply the domain values to it.

override fun update(product: Product): Product {
 val entity = productJpaRepository.findByIdOrNull(product.id)
 ?.also { it.update(product) }
 ?: throw CoreException(ErrorType.NOT_FOUND, "Product not found.")

 return productJpaRepository.save(entity)
 .let(ProductMapper::toDomain)
}

Initially, I wondered why update called findById when I had already loaded the Product.

With separate models, however, the Product held by the application layer is not a managed entity. To use JPA dirty checking, infrastructure needs to obtain the managed entity and apply the changes there.

This introduces another lookup, but preserves both the JPA persistence context behavior and the separation of the domain model.

4. Don’t force every query through a domain model

I decided that separating the models didn’t mean every query had to return a domain object.

Sorting and pagination were central to the product list. Once like counts were moved into ProductStat, likes_desc also needed to sort using that data. ProductQueryRepository therefore returns ProductSummary through a QueryDSL projection.

The placement of ProductSummary is still an open question. It currently lives under a domain DTO package, but an application read model or infrastructure projection may be a better home.

What I would question about the earlier design

Three issues stood out during this work.

First, services were doing too much. When repository calls, business validation, and coordination across domains all live together, the service grows with every feature. This time, I separated the Facade, Application Service, and Domain Service responsibilities.

Second, entity names mixed domain and database concepts awkwardly. A class named UserEntity mapped to a table named member. Now the domain uses User and infrastructure uses MemberEntity.

Third, separation itself could become the goal. Separate models mean more files and conversion code; they don’t automatically improve every feature. A small CRUD project may be simpler if its JPA entities also serve as domain models.

In this project, product, like, order, and inventory rules were likely to grow, so the separation felt worthwhile.

Retrospective

Keep:
- Express business rules in domain models.
- Keep Repository interfaces in the domain and implementations in infrastructure; this helped testability and dependency direction.
- Use clear persistence model names such as MemberEntity to make imports and responsibilities easier to follow.
Problem:
- Mapper code is repetitive.
- Reloading a managed entity during updates made the flow initially unintuitive.
- DTO-like objects such as ProductSummary and ProductCatalog still live under the domain, leaving the boundary between domain models and read models unclear.
- Methods such as Entity.update(domain) mean the separation isn’t completely clean.
Try:
- Consider moving query-only models into application read models or infrastructure projections.
- Check for unnecessary update lookups, and revisit command-based update queries or the dirty checking strategy if performance becomes a problem.
- Add Mapper tests if entity-to-domain conversion rules become more complex.
- Start with domains that have business rules rather than separating every simple CRUD model by default.

Deep dive

The underlying idea

Creating two copies of an object isn’t the point. The point is separating reasons for change.

A domain model expresses business rules. For example, Inventory.quantity must not be negative. A database check constraint can enforce that too, but the domain should enforce it as well. That allows order creation tests to verify insufficient inventory without a database.

class Inventory(
 val id: Long = 0L,
 val productId: Long,
 quantity: Long,
) {
 var quantity: Long = quantity
 private set

 init {
 if (quantity < 0L) {
 throw CoreException(ErrorType.BAD_REQUEST, "Inventory quantity must not be negative.")
 }
 }

 fun deduct(quantity: Long) {
 if (quantity <= 0L) {
 throw CoreException(ErrorType.BAD_REQUEST, "Deduct quantity must be positive.")
 }
 if (this.quantity < quantity) {
 throw CoreException(ErrorType.CONFLICT, "Inventory quantity is insufficient.")
 }

 this.quantity -= quantity
 }
}

A database entity expresses the storage structure. For example, OrderEntity describes the relationship between the orders and order_item tables.

@Entity
@Table(name = "orders")
class OrderEntity(
 @Column(name = "order_number", nullable = false)
 var orderNumber: String,

 @Column(name = "member_id", nullable = false)
 var memberId: Long,

 @Enumerated(EnumType.STRING)
 @Column(nullable = false)
 var status: OrderStatus,

 @Column(name = "total_amount", nullable = false)
 var totalAmount: Long,

 @Column(name = "ordered_at", nullable = false)
 var orderedAt: ZonedDateTime,
) : BaseEntity() {
 @OneToMany(mappedBy = "order", cascade = [CascadeType.ALL], orphanRemoval = true)
 @BatchSize(size = 50)
 val items: MutableList<OrderItemEntity> = mutableListOf()

 fun addItem(item: OrderItemEntity) {
 items.add(item)
 item.order = this
 }
}

The Order domain model expresses the business result of an order.

class Order(
 val id: Long = 0L,
 val orderNumber: String,
 val memberId: Long,
 val status: OrderStatus,
 val items: List<OrderItem>,
 val totalAmount: Long,
 val orderedAt: ZonedDateTime,
) {
 init {
 if (items.isEmpty()) {
 throw CoreException(ErrorType.BAD_REQUEST, "Order items must not be empty.")
 }
 if (totalAmount != items.sumOf { it.totalAmount }) {
 throw CoreException(ErrorType.BAD_REQUEST, "Order total amount is invalid.")
 }
 }
}

The objects look similar, but their responsibilities differ. OrderEntity knows about JPA cascade, batch fetching, and table mappings. Order knows that an order must contain items and that totalAmount must equal the sum of the item amounts.

How this worked in my project

Creating an order required Product, Brand, Inventory, and Order to cooperate.

OrderFacade in the Application Layer retrieves the required data and establishes the transaction boundary. The Domain Service, OrderPlacementService, checks that products, brands, and inventory exist, deducts stock, and creates order snapshots.

class OrderPlacementService {
 fun place(
 memberId: Long,
 items: List<OrderPlacementItem>,
 products: List<Product>,
 brands: List<Brand>,
 inventories: List<Inventory>,
 ): OrderPlacementResult {
 val productById = products.associateBy { it.id }
 val brandById = brands.associateBy { it.id }
 val inventoryByProductId = inventories.associateBy { it.productId }

 val orderItems = items.map { item ->
 val product = productById[item.productId]
 ?: throw CoreException(ErrorType.NOT_FOUND, "Product not found.")
 val brand = brandById[product.brandId]
 ?: throw CoreException(ErrorType.NOT_FOUND, "Brand not found.")
 val inventory = inventoryByProductId[product.id]
 ?: throw CoreException(ErrorType.NOT_FOUND, "Inventory not found.")

 inventory.deduct(item.quantity)
 OrderItem.snapshot(
 productId = product.id,
 productName = product.name,
 brandName = brand.name,
 unitPrice = product.price,
 quantity = item.quantity,
 )
 }

 return OrderPlacementResult(
 order = Order.createCompleted(memberId = memberId, items = orderItems),
 inventories = inventories,
 )
 }
}

OrderPlacementService knows nothing about JPA or ProductEntity, InventoryEntity, and OrderEntity. It accepts domain objects and applies the rules.

That was the biggest benefit I gained from the separation.

When might separation be unnecessary?

Separating domain models from database entities isn’t always the best choice. Using JPA entities as domain models may be reasonable when:

The project mostly consists of simple CRUD.
There are few business rules.
The table structure closely matches the API requirements.
Database dependencies aren’t a significant problem in tests.
The team is unfamiliar with separate models and productivity matters more.

Separation is worth considering when:

Domain rules are growing.
Multiple Aggregates or domains cooperate.
Database structures and business models may change independently.
JPA annotations or associations intrude on domain code.
Unit tests need to verify rules without a database.
Read queries and command models have different requirements.

Here, products, brands, likes, inventory, and orders worked together, with core rules such as deducting inventory during order creation. That made separation a better fit.

You Can Do DDD, Too!

Fri, 22 May 2026 17:00:00 +0900

I suspect plenty of developers are like me: we’ve heard of DDD, but haven’t really put it into practice.

At its core, the idea is fairly straightforward:

Understand the business, then design around that understanding.

Everyone involved in solving the problem develops a shared understanding of the domain and uses it to guide the design, rather than starting with technology.

DDD is more concerned with “What problem are we actually solving?” than “Which framework should we use?”

Why did DDD emerge?

Software gets more complicated over time.

At first, things are simple: receive a request in a controller, process it in a service, and save the result to a database.

As features accumulate, though, things start to look like this:

The order service decides which coupon policies apply.
The payment service checks membership grades.
Shipping logic directly changes order status.
User, Member, and Customer appear throughout the code with similar meanings.
Someone asks, “Why is this condition here?” and everyone suddenly looks away.

The problem is bigger than long source files. Business knowledge has become scattered across the system.

Eric Evans introduced DDD in his 2003 book, Domain-Driven Design: Tackling Complexity in the Heart of Software, as an approach to managing this complexity. Its focus is the domain.

A domain is the business problem area the software addresses. In commerce, examples include orders, payments, inventory, delivery, and settlement.

DDD aims to develop a deep understanding of those areas and reflect that understanding in the names, structure, and responsibilities of the code.

Three parts of DDD

The terminology can feel overwhelming when you first study DDD. I find it easier to organize it into three broad parts.

1. Domain exploration

This is where we get to know the domain.

Domain experts and developers examine business workflows together: what happens, which policies apply, and where problems occur.

Methods such as EventStorming can help. For example, we can lay out events such as “Order Created,” “Payment Approved,” “Inventory Deducted,” and “Delivery Started” to see the workflow as a whole.

2. Strategic Design

Strategic Design defines the larger boundaries.

Instead of building one enormous model for the entire system, we divide it into areas where meanings remain consistent. Bounded Context is a key concept here.

For a commerce system, one possible division is:

Order: order creation, order status, and cancellation
Payment: payment approval, cancellation, and payment gateway integration
Inventory: stock reservation, deduction, and restoration
Delivery: shipment requests, tracking numbers, and delivery status

These boundaries shouldn’t simply follow folders or tables. Language, rules, responsibilities, and reasons for change are more useful criteria.

3. Tactical Design

Tactical Design is about expressing the inside of a Bounded Context in code.

This is where patterns such as Entity, Value Object, Aggregate, Repository, Domain Service, Domain Event, and Factory come in.

Using those patterns doesn’t automatically make a design DDD, though.

If all business logic still lives in a single OrderService and the domain objects are empty shells with getters and setters, naming a package domain doesn’t accomplish much.

Still unsure what a Bounded Context is?

If I had to pick the most important concept in DDD, it would be Bounded Context.

A Bounded Context defines the boundary within which a particular model and its terminology have consistent meanings.

Take the word “product.”

The inventory team cares about incoming stock and quantities available to ship. The settlement team cares about selling prices, supply costs, and commission rates.

They’re talking about the same product from different perspectives.

What happens if we put everything into one Product model?

At first, it feels convenient to have everything in one place. Eventually, it becomes a huge object nobody wants to touch.

The lesson is: when the same word has different meanings, consider separate boundaries.

How do we identify domain boundaries?

Finding useful criteria for splitting domains was one of the harder parts of learning DDD. These four questions helped me.

Does the same word mean different things?

If teams use words such as “member,” “product,” “order,” or “settlement” differently, that’s a potential boundary.

A member might be an authenticated identity in an authentication context, buyer information in an order context, and a campaign recipient in a marketing context.

A shared word doesn’t necessarily call for a shared model.

Who owns this rule?

Payment approval rules belong to the payment domain. Stock deduction rules belong to inventory. Coupon eligibility belongs to the coupon domain.

When one domain starts applying another domain’s rules directly, validation can be skipped, history can be lost, and unintended side effects can appear.

This matters in practical DDD implementations, too. A change to a limit balance, for example, should go through the domain responsible for that limit. That keeps validation, history, and policy enforcement in one place.

Must these changes happen in one transaction?

An Aggregate is more than a container for objects that look related. It is closer to the smallest unit whose consistency must be maintained immediately.

An order total may need to match the sum of its items immediately. Sending a notification or updating statistics after the order completes may be allowed to happen later.

Putting everything in one transaction makes the model too large. Routing everything through events can make the flow hard to follow.

The useful distinction is: what must be consistent immediately, and what can become consistent later?

Do these things change together or independently?

Things that frequently change together are likely to belong within the same boundary. Things that change for different reasons are candidates for separation.

Promotion policies change with marketing campaigns. Delivery integration changes with carrier APIs or logistics policies. Settlement changes with accounting, contracts, and commission policies.

When unrelated reasons for change share one model, they keep getting in each other’s way.

A practical view of the tactical patterns

Entity: an object whose identity matters, such as an order or a member.
Value Object: an object whose value matters, such as money, an address, or a period of time.
Aggregate: a unit of change within which consistency must be maintained.
Repository: an interface for storing and retrieving objects.
Domain Service: domain rules that don’t fit naturally in a single object.
Domain Event: a meaningful occurrence in the domain.
Factory: an object responsible for complex object creation.

The pattern names matter less than whether the business rules are visible in the code.

For example, we could pass a price around as a Long. But if an amount cannot be negative, needs a currency, or follows calculation rules, a Price Value Object may express that more clearly.

Computers aren’t the only things that read code. Future me reads it, too. And future me is already annoyed. Let’s give that person a break.

Is DDD the same as microservices?

No. A Bounded Context is a design boundary; it doesn’t have to be a deployment boundary.

Adopting DDD doesn’t mean splitting everything into separate services from day one. A modular monolith can often be a good starting point.

We can first enforce boundaries through packages, modules, and dependency rules within one application. If independent deployment becomes necessary later, we can split out a service then.

DDD doesn’t require the full collection of Kafka, Event Sourcing, CQRS, and MSA. Sometimes that’s just an excuse to collect more tools.

A quick look at the Anti-Corruption Layer

External and legacy systems inevitably have models that differ from ours.

If we bring those models directly into our domain, our internal model gradually takes on their assumptions. For example, if a payment provider’s status values spread throughout our payment domain, changing providers can affect code across the system.

An Anti-Corruption Layer provides a translation layer between them. It protects the internal domain by translating the external system’s language into our own.

A simple analogy is using a USB-C hub to connect HDMI to a MacBook Air: MacBook ↔ USB-C hub ↔ HDMI.

// ACL example

class LegacyOrderTranslator {

 fun translate(legacyStatus: String): OrderStatus =
 when (legacyStatus) {
 "A" -> OrderStatus.PAID
 "B" -> OrderStatus.SHIPPED
 else -> throw IllegalArgumentException("Unknown status: $legacyStatus")
 }
}

What I’ve taken away

DDD has clear benefits when used well.

Business rules become easier to find in code. We can see where policies live and better predict the impact of a change.
Team conversations become closer to the code. When product planners and domain experts use terms that also appear in the implementation, there is less room for misunderstanding requirements.
We don’t have to understand a complex system all at once. Bounded Contexts let us reason about each area separately instead of memorizing the entire system.

Still, I don’t think DDD belongs everywhere. Applying it heavily to simple CRUD or features with very few policies can introduce unnecessary complexity.

It seems most useful when the domain itself is complex: many rules, many exceptions, frequent changes, and multiple teams using the same words differently.

The idea I keep coming back to is:

Bring the business and the code closer together.

See? You can do DDD, too.