Different kinds of help
A team may have a sound description of its services yet leave retries or version changes undecided. The sources below help with different parts of that work. They can be combined within an existing delivery method.
| Approach or asset | Useful contribution | Further decisions for the architect |
|---|---|---|
| C4 system context diagrams | Show a system with the people and other systems it interacts with. | Use the wider picture to locate responsibilities, then describe the operations and their failure behaviour in linked records. |
| Enterprise Integration Patterns | Names recurring messaging problems and design choices, including handling repeated messages. | Select a pattern for the failure and operating conditions; assign recovery and support. |
| OpenAPI | Describes application programming interfaces (APIs) that use HTTP, the protocol used for web requests. | Agree business meaning, acceptance, compatibility and operational behaviour alongside the description. |
| AsyncAPI | Describes message-driven interfaces, their channels and operations without prescribing how services are arranged. | Set delivery, ordering, duplication and recovery rules for the chosen transport and consumers. |
| CloudEvents | Defines common event details, including an event’s source and identity. | Define the event’s business meaning, access, retention and consumer behaviour. |
| Model Context Protocol (MCP) | Defines how artificial intelligence (AI) applications discover and call tools, including descriptions of their expected inputs and, where supplied, outputs. | Decide permitted actions, validate results and assign responsibility for uncertain or failed work. |
These diagrams, patterns and interface specifications address particular design questions. The broader business and organisation comparisons discuss methods that can place them within architecture and delivery work.
Interaction choices
| Choice | Where it helps | Trade-off to examine |
|---|---|---|
| Request and response | The caller needs a result before continuing. | A timeout can leave the result unknown; retries and status lookup need agreement. |
| Queued command | Work can wait while the receiving service is busy or unavailable. | Receipt and completion differ; someone must handle work that expires or repeatedly fails. |
| Published event | Several consumers need to react to an accepted fact. | Consumers may lag, receive duplicates or see events out of order; correction and reconciliation matter. |
| Batch or file exchange | Scheduled transfer suits the business timing or an existing supplier interface. | Define a complete batch, partial rejection, duplicate files, corrections and a reconciliation total. |
These are illustrative choices. A service can use a request to accept a handover, an event to notify other systems and a batch to reconcile a report.
With orchestration, a coordinator records and directs a sequence of work. With choreography, participants react to messages and events from one another. For either arrangement, identify who can tell whether the whole case has completed and who investigates an incomplete sequence.
A safe repeat
An idempotent operation gives the same intended effect when repeated. For example, a repeated acceptance request should refer to the original transfer rather than create another one. Retain an operation identity and its result for an agreed period, and reject reuse of that identity with a changed request. This draws on the Idempotent Receiver pattern and Amazon Web Services (AWS) guidance on safe retries.
A repeated request and a new request based on stale information are different cases. The worked example uses an operation identity for the first and a case version for the second. HTTP conditional requests provide one mechanism for guarding against conflicting updates; see HTTP Semantics, RFC 9110, If-Match.
Acceptance and conflict
The contract needs to say when a proposed action becomes accepted, and what happens if the information on which it depends has changed.
An offline screen may hold local work while the service has moved on. The Android offline-first guidance describes queued writes and conflict resolution. For the cancellation example, a local timestamp cannot by itself authorise an ownership transfer: acceptance must still meet the service’s rules.
A tool call needs an acceptance rule too. The MCP tools specification requires server input validation and access controls, and addresses client checks and timeouts. A valid message shape does not establish that an action proposed by an AI assistant is appropriate. In this example, AI may propose a summary; a named person accepts responsibility through the case service.
Inside the application
A component diagram can show where a rule belongs. A decision table can explain the rule itself. A check can show whether its implementation behaves as intended. Choose the combination that answers the design question.
| Approach or asset | Useful contribution | Decision still needed |
|---|---|---|
| C4 component diagrams | Describe responsibilities and dependencies inside an application or data store—the level C4 calls a container. | Choose the useful level of detail and keep the view consistent with the code. |
| Ports and adapters | Separate application behaviour from the mechanisms used to call it and obtain external services. | Decide which dependencies merit an interface and how the real adapter is checked. |
| Domain-driven design | Organise software around business meaning and explicitly related models. | Agree the scope in which terms have one meaning, and how other models translate them. |
| Decision Model and Notation (DMN) | Describes decisions and their information requirements, including decision tables. | Set rule ownership, rule precedence, exception handling and the implementation’s supported semantics. |
| A portfolio of tests | Combines fast, focused checks with checks across components and complete user journeys. | Select checks for distinct failure risks and maintain their expected results. |
These approaches can work together. A diagram does not require every component to be deployed separately, and adopting a decision notation does not settle how the software stores an accepted change.
Ways to organise behaviour
| Choice | Useful when | Trade-off |
|---|---|---|
| Functions with explicit inputs and results | A decision or transformation can be described without hidden state. | The surrounding application still owns persistence, permissions and effects. |
| Objects or modules that own state | Related operations must preserve a common set of rules. | Shared or hidden mutable state can make concurrency and tests harder to reason about. |
| Decision tables or executable rules | People need to review combinations of business conditions. | Ambiguous overlaps, missing cases and engine-specific behaviour need checking. |
| Coordinated steps | Work combines validation, computation, model calls and external effects. | Each step needs a contract, failure route and retained state where work can resume. |
The transfer example combines a decision function with an operation handler and a transactional store. A proposed summary follows a separate path through generation, checking and human review.
Decisions between steps
Google’s Agent Development Kit (ADK) describes graph-based workflows for connecting steps and routes. Its evaluation guidance considers tool use as well as final responses. These mechanisms prompt useful questions: what crosses each connection, who can change it, what happens on failure, and what result permits the next action?
Workflow structure can be predictable while a model’s output varies. A result can have the required structure and still misstate the case. Structural checks, comparison with source facts and a person’s review serve different purposes.
Methodology configuration
Map the descriptions to your application catalogue, interface contracts, component model, rule catalogue and test plan. Link the business meaning to its implementation and checks. The configuration guidance helps place those records within your method.
Sources and editions
Primary references checked in September 2026:
- Enterprise Integration Patterns: Idempotent Receiver, selected pattern.
- OpenAPI specification 3.2.1, dated 10 September 2026.
- AsyncAPI specification 3.0.0, selected edition.
- CloudEvents specification 1.0.2, selected edition.
- MCP tools specification, 25 November 2025, selected edition.
These selected references cover the interface and interaction choices above.
Software and business rules
Primary material checked in September 2026:
- C4 component diagrams, author guidance on scope and usefulness.
- Alistair Cockburn: Hexagonal architecture, original 2005 article on ports and adapters.
- Martin Fowler: Bounded Context, 15 January 2014; a focused explanation of domain-driven design.
- Object Management Group (OMG) DMN 1.5, adopted August 2024; selected edition, with the OMG overview.
- Ham Vocke: The Practical Test Pyramid, 2018; selected sections on scope, feedback and redundant tests.
Together, the references support a comparison of selected contributions. Applying them in a real service requires its operating context, design choices and trial results.