Skip to content

Messaging & Integration

Messaging and integration patterns allow your back-end to communicate reliably with other systems and services. Instead of only making direct request/response calls, you can use queues, topics, and events to decouple components, handle spikes in load, and integrate with external systems. Good integration design makes your system more resilient and easier to evolve over time.

For this product, you describe how your application communicates with other services (internal or external), which messaging or integration patterns you use, and how you handle reliability and error cases.

Messaging & Integration in Back-end Systems

Common patterns and technologies include:

  • Message queues (for example RabbitMQ, SQS) for asynchronous work
  • Publish/subscribe for broadcasting events
  • Event-driven architectures using domain events
  • Webhooks and HTTP-based integrations
  • Idempotency and retry logic for reliable processing

In your project you select patterns that make sense for your context (for example background processing, external APIs, or other services).

Quality indicators

When assessing this product, the following quality indicators will be considered:

  • The messaging & integration document is self-contained, with an introduction/context and then a description of the chosen approach.
  • It describes which external or internal systems the application integrates with.
  • It explains which messaging or integration patterns are used (queues, pub/sub, events, webhooks, etc.) and why.
  • It describes message formats or API contracts and how they are versioned or evolved.
  • It explains how reliability is handled (retries, dead-letter queues, idempotency).
  • It includes examples of code or configuration that implement messaging or integrations, with references to the code in GitLab.
  • It describes how these integrations are tested (for example integration tests, contract tests, mocks).
  • It includes a list of sources used to design and implement messaging and integration.

Template

To document messaging and integration in your own project, you can use the following template:

# Messaging & Integration

In this section, describe in a few sentences why your application needs to communicate with other systems and what kind of interactions are involved. This is the main text of your document.

## Context & Systems

Here you describe the context:
- Which other systems or services are involved
- Which data or operations need to be exchanged

## Patterns & Technologies

Here you describe which patterns and technologies you use:
- Message queues, pub/sub, events, webhooks, or simple HTTP calls
- Why you chose these patterns

## Message Formats & Contracts

Here you describe the structure of messages or API contracts:
- Payload formats (JSON, XML, etc.)
- Versioning strategy

Add examples and references to the code in GitLab.

## Reliability & Error Handling

Here you describe how you handle failures:
- Retries and backoff
- Idempotency
- Dead-letter queues or error logs

## Sources

List here the sources you used to design and implement messaging and integration (documentation, articles, videos, books, etc.).
Also include sources that helped you write the code.