Your system publishes an event:

ProcessPaymentRequested

A payment service receives it and processes a payment.

Is that an event or a command?

The distinction isn't about whether you use Kafka, RabbitMQ, or another message broker.

It's about what the message means.

1. Events describe facts

An event communicates something that already happened.

Examples:

OrderPlaced
PaymentCompleted
InventoryReserved
CustomerRegistered

Consumers decide whether they need to react.

An OrderPlaced event might trigger analytics, notifications, or other independent processes.

The publisher doesn't need to know every consumer.

2. Commands request actions

A command communicates something that should happen.

Examples:

ProcessPayment
ReserveInventory
CancelOrder
SendInvoice

Commands express intent and responsibility.

Usually, a particular component owns the capability required to execute them.

A command might be delivered asynchronously, but asynchronous delivery doesn't turn it into an event.

3. Messaging doesn't automatically remove coupling

Consider:

OrderService
    ↓ publishes PaymentProcessingRequested
PaymentService
    ↓ must process payment

If the order workflow depends on the payment service performing this action, the relationship is still a dependency.

Publishing the instruction through an event broker doesn't eliminate that dependency.

Events work well for announcing facts.

Commands work well for requesting actions.

Choose the message based on the communication semantics, not the transport technology.

Your domain model contains everything needed to protect business rules.

Your API needs five fields.

Do you really need to load the entire aggregate to return those fields?

Not necessarily.

Commands and queries have different responsibilities.

1. Your domain model protects invariants

Consider an Order aggregate:

Order
 ├── Customer
 ├── OrderItems
 ├── Payments
 ├── Discounts
 ├── Shipping
 └── Business Rules

The model exists to ensure valid state transitions.

It might enforce rules such as:

An order cannot be paid twice.

A canceled order cannot be shipped.

Discounts must satisfy eligibility rules.

Those responsibilities matter when changing the order.

They might not matter when displaying an order summary.

2. Queries need data, not behavior

Imagine a dashboard that needs:

{
  "orderId": 123,
  "customerName": "Alex",
  "total": 149.99,
  "status": "Paid"
}

Instead of reconstructing the full aggregate, a query can return a projection:

SELECT
    o.Id AS OrderId,
    c.Name AS CustomerName,
    o.Total,
    o.Status
FROM Orders o
JOIN Customers c ON c.Id = o.CustomerId
WHERE o.Id = 123;

The query returns the data required by the consumer.

No domain aggregate reconstruction is necessary.

3. Separate responsibilities without overengineering

CQRS doesn't require separate databases, event sourcing, or additional microservices.

You can separate commands and queries inside the same application.

Commands use domain models to enforce business rules.

Queries use projections optimized for their consumers.

If a read operation doesn't need domain behavior, it doesn't need to load that behavior.

Every request has a trace ID. Every service propagates it. Your tracing dashboard shows exactly where requests traveled.

Then production breaks.

You find the failed trace, but still need to figure out which business operation failed.

A trace ID connects technical operations. It doesn't automatically explain their business meaning.

1. Technical traces lack business context

Consider this trace:

POST /api/orders        850ms
  ├── OrderService      120ms
  ├── PaymentService    680ms
  └── SQL INSERT         50ms

You know where time was spent.

But what was happening?

Was the customer placing a new order? Was this a payment retry? Was the workflow waiting for authorization?

Technical traces describe execution. They don't necessarily describe intent.

2. Add domain context to spans

OpenTelemetry supports custom span attributes.

For example:

operation.name = order.checkout
order.status = payment_pending
payment.provider = stripe
workflow.step = payment_authorization

Now your trace describes both technical execution and the business operation.

Prefer low-cardinality attributes for aggregation. Keep sensitive values out of telemetry, and place high-cardinality identifiers in appropriately controlled searchable logs or traces when supported by your backend.

3. Design observability around questions

Before adding more telemetry, identify the questions engineers need to answer:

Which business operation failed?

At which workflow step?

Which dependency caused the delay?

Is the problem isolated to one operation type?

How many operations are affected?

Instrument the system to answer those questions.

A trace ID helps you find the request.

Business context helps you understand what happened.

Cursor announced a new Legacy Code Mode, designed to help developers identify code nobody remembers writing.

The editor automatically marks code as legacy when more than two weeks have passed since its last AI-assisted modification.

According to Cursor, two weeks represents the point where neither the developer nor the AI agent has enough context to safely explain why the code exists.

“We found developers were spending too much time trying to understand code generated earlier this month.”

When Legacy Code Mode detects such code, Cursor discourages direct modification and recommends the industry-standard alternative: creating a new service.

If developers still attempt to change the original implementation, Cursor displays a warning:

“This code appears to be working. Are you sure?”

Your architecture diagram says:

API → Application → Domain
         ↑
   Infrastructure

Your code might have other ideas.

Someone adds:

Domain → Infrastructure

Then:

Application → API

Six months later, the diagram is still beautiful.

One way to protect important boundaries is with architecture tests.

For example, you can define rules such as:

Domain must not depend on Infrastructure

Application must not depend on API

Controllers must not access repositories directly

Then run those rules as part of your test suite and CI pipeline.

Architecture tests are useful for enforcing things such as:

• Layer dependencies
• Namespace boundaries
• Module isolation
• Naming conventions
• Dependency restrictions
• Clean Architecture rules

They don't prove that your architecture is good.

They prove that specific structural rules you decided were important are still being followed.

Documentation describes the intended architecture.

Tests can check whether the code agrees.

If an architecture rule matters enough to put on the diagram, it might matter enough to test.

Retries improve resilience when failures are temporary.

They can also increase load exactly when a dependency is already struggling.

Imagine a service receiving:

1,000 requests/sec

The dependency starts failing.

Your policy retries every request three times.

Now the dependency might see something closer to:

Original traffic:  1,000
Retry #1:          1,000
Retry #2:          1,000
Retry #3:          1,000
                    -----
Potential traffic: 4,000 requests/sec

And that's before considering retries at multiple layers.

Service A retries Service B.

Service B retries Service C.

The client retries Service A.

A reliability mechanism can become a traffic multiplier.

Good retry policies usually consider:

• Whether the failure is transient
• Exponential backoff
• Jitter
• Maximum attempts
• Retry budgets
• Request deadlines
• Retry-After guidance
• Whether another layer is already retrying

Retries don't create capacity.

If a dependency is overloaded, sending it more requests immediately might not be the recovery strategy you want.

Retry when another attempt has a reasonable chance of succeeding.

Then give the dependency some time before asking again.

Caching isn't only about deciding what data to store.

You also need to decide what makes that data unique.

Suppose you cache product information:

product:42

Looks reasonable.

Then you discover that the product 42 has different prices by country:

product:42:PL
product:42:DE

Then prices differ by currency:

product:42:PL:PLN
product:42:DE:EUR

Then the application becomes multi-tenant:

tenant:17:product:42:PL:PLN

Your cache key quietly contains assumptions about your data model.

It determines:

• What data is considered equivalent
• Which requests can share cached data
• Tenant and user isolation
• How invalidation works
• Cache cardinality
• Whether callers receive the correct result

A missing dimension can cause incorrect cache hits.

Too many dimensions can destroy your hit rate and create excessive cardinality.

Before writing:

cache.Set("products", value)

Ask what uniquely identifies the value you're caching.

Your cache doesn't understand your domain.

Your cache key has to explain it.

Adding an idempotency key to an API doesn't automatically make the operation idempotent.

The key needs to identify the operation you want to execute once.

Consider payment creation:

POST /payments
Idempotency-Key: order-123-payment

The client times out and retries:

POST /payments
Idempotency-Key: order-123-payment

The server recognizes the same logical operation and returns the previous result instead of creating another payment.

Now imagine generating a new key for every retry:

Request 1 → 7f9a...
Request 2 → 82bc...
Request 3 → a14e...

From the server's perspective, those are three different operations.

A good idempotency key should match the scope of the business operation.

Think about:

• What exactly should happen once?
• How long should the key remain valid?
• Which caller owns the key?
• Should the same key with different payloads be rejected?
• Where is the result of the original operation stored?

Idempotency isn't about making requests unique.

It is about recognizing when multiple requests represent the same operation.

If every retry gets a new identity, the server has no reason to know it's a retry.

Two users read the same record:

• Both modify it
• Both save it

Who wins?

Without concurrency protection, the second write might silently overwrite the first.

One common solution is optimistic concurrency.

For example, keep a version number with the record:

Order
Id: 42
Status: Pending
Version: 7

Update it only if the version is still 7:

UPDATE Orders
SET Status = 'Completed',
    Version = 8
WHERE Id = 42
  AND Version = 7;

If zero rows are updated, somebody changed the record after you read it.

Your application can then reject, retry, merge, or ask the user to resolve the conflict.

If multiple actors can update the same data, checking whether it changed before overwriting it is often useful.

Application feels slow?

Before optimizing it, find out what is slow.

Use profiling, tracing, metrics, or benchmarks to measure where the application spends its time.

You might discover that a request spends:

Validation        4 ms
Business logic   12 ms
Database        680 ms
Serialization     8 ms

Optimizing 12 ms of business logic probably won't fix a 700 ms request.

Measure things like:

• Execution time
• Database calls
• External requests
• CPU usage
• Memory allocations
• Lock contention

Then optimize the part responsible for the problem.

Performance optimization becomes much easier once you know what needs to become faster.