Skip to main content

Design and Operational Guidance

This page explains how to reason about systems built on RelayX.

It is not an API guide.
It is not a feature list.

It explains how RelayX behaves in the real world and how you should design around that behavior so your system keeps working during crashes, retries, reconnects, and load spikes.

If you understand this page, the rest of the documentation will feel obvious.

Think of RelayX as Infrastructure You Don’t Have to Run​

RelayX exists so you don’t have to build or operate real-time infrastructure yourself.

You do not need to:

  • Run message brokers
  • Manage persistent connections
  • Build fan-out systems
  • Handle ordering at scale
  • Design retry and redelivery logic from scratch

RelayX takes care of those problems.

What it does not do is guess how your application should behave when things fail.

RelayX handles infrastructure problems.
Your application handles product logic.

Separate “Sending” From “Handling”​

A core idea in RelayX is that sending a message is not the same as handling it.

  • Producers send messages.
  • Subscribers handle messages.
  • These two sides are intentionally decoupled.

From the producer’s point of view:

  • Messaging is fire-and-forget.
  • You send a message and move on.
  • You do not wait for subscribers.
  • You do not track delivery or retries.

From the subscriber’s point of view:

  • Messages arrive in order.
  • Messages may be redelivered if handling fails.
  • Your code must be safe to run again.

Thinking this way prevents tight coupling and avoids blocking systems on each other.

Expect Retries, Not Perfection​

RelayX is built on the assumption that things fail.

That means:

  • Subscriber processes crash
  • Workers restart
  • Connections drop
  • Timeouts happen

When this happens, RelayX does not panic or invent new behavior. It follows clear rules.

For example:

  • Messages are redelivered if subscriber handling fails
  • Jobs are redelivered if workers crash or fail to acknowledge
  • Ordering and deduplication rules stay the same during retries

Retries are not edge cases.
They are normal behavior.

If your system breaks when something runs twice, it will break in production.

Understand What RelayX Guarantees and What It Does Not​

RelayX makes strong backend guarantees, but they are narrow and specific.

RelayX guarantees things like:

  • How messages are ordered
  • When messages or jobs are redelivered
  • What deduplication means
  • When work is considered complete

RelayX does not guarantee:

  • Exactly-once execution of your code
  • That side effects only happen once
  • That state updates cannot be overwritten
  • That retries are always safe

Do not build systems that rely on guarantees RelayX does not claim to provide.

Design Handlers to Be Safe to Run Again​

Because retries happen, handler code should be written with this in mind.

Good handlers:

  • Can run more than once without breaking things
  • Check state before applying changes
  • Avoid irreversible side effects without safeguards

Bad handlers:

  • Assume “this will only run once”
  • Perform partial side effects without checks
  • Rely on timing or ordering across systems

RelayX will not protect unsafe handlers from themselves.

Think in Terms of Delivery, Not Success​

RelayX delivers messages and jobs.
It does not decide whether your business logic succeeded.

A message being delivered does not mean:

  • The user action succeeded
  • The database update committed
  • The external API call completed

It only means:

  • RelayX delivered the message
  • Your code was given a chance to handle it

Success is defined by your application, not by RelayX.

Use the Right Tool for the Job​

RelayX gives you multiple tools because different problems need different rules.

  • Use Messaging to notify subscribers about events
  • Use Queues for background work that must be acknowledged
  • Use the Key-Value Store to share small pieces of state

Do not force one tool to behave like another.

If you use Messaging like a queue, or the Key-Value Store like a database, things will fail in subtle ways.

Backpressure Is a Reality, Not a Bug​

Under load, RelayX may slow down delivery.

This is expected.

RelayX prefers:

  • Slower delivery
  • Predictable behavior
  • Preserved guarantees

over:

  • Dropping messages silently
  • Breaking ordering
  • Inventing unsafe shortcuts

Your system should be able to tolerate slower delivery during peak load.

Build for Recovery, Not Prevention​

You cannot prevent all failures.

Instead of trying to stop every possible failure, design your system so it can recover:

  • Handlers can run again
  • State can be rebuilt
  • Missed messages are acceptable
  • Temporary inconsistency is survivable

RelayX supports recovery by making behavior predictable.

A Useful Mental Shortcut​

If you remember nothing else, remember this:

  • RelayX handles delivery
  • Your code handles correctness

RelayX will get messages and jobs to your code in a clear, documented way.

What your code does with them is your responsibility.

Why This Mental Model Works​

Teams that think this way:

  • Integrate RelayX faster
  • Debug issues more easily
  • Avoid unsafe assumptions
  • Build systems that survive real failures

RelayX is not trying to make distributed systems disappear.

It is trying to make them understandable enough that you can build on them with confidence.

That is how you should think about RelayX.



Need Help?

Join our Discord server, post your concern & someone from our team will help you out ✌️