Use decision records to make serverless boundaries reviewable

Most serverless systems do not fail because a team chose the wrong AWS service. They become difficult when important choices were made implicitly: who owns an event, which system retries a failed request, whether a resource is allowed to write, or how a change can be undone.

A short decision record makes those choices reviewable while they are still cheap to change. It does not need to be a long architecture document. It needs to say what was decided, why it fits the workload, and which trade-off the team is accepting.

Start with the boundary, not the service

The useful unit of an architecture decision is usually a boundary. Examples include the boundary between an API and an asynchronous worker, between a producer and a subscriber, or between a discovery tool and a customer AWS account.

For each boundary, record four things:

• the owner on each side;
• the data or event that may cross it;
• the failure and retry behavior;
• the permissions required to operate it.

This moves the conversation away from “should we use EventBridge or SQS?” and toward the question that matters first: is this a published fact that several teams may react to, or a piece of work with one accountable consumer?

Write down the rejected alternative

An architecture record is most valuable six months later, when someone needs to understand why an apparently obvious alternative was not used. Include the next-best option and the reason it did not fit at the time.

For example, a team may keep a synchronous API call because the caller needs a confirmed result in the same interaction. The record should also say why the team did not put the command on a queue: perhaps the business process has no acceptable delayed-success experience yet. That gives a future team a clear condition for revisiting the decision.

Make access part of the record

IAM is often documented after the system shape has already hardened. Capture it with the decision instead. State which role is assumed, which actions are needed, and whether the operation is read-only or changes production state.

That discipline is especially useful for tools connected to AWS accounts. A tool that discovers resources should not inherit deployment permissions merely because both capabilities are convenient in one product. Separate roles keep the trust decision visible and independently revocable.

Keep the record close to the code

Store decisions next to the CDK and application code they affect. Link the record from the relevant construct, runbook, or pull request. When the assumptions change, update the record in the same review as the implementation.

The goal is not process for its own sake. It is to give an engineer joining the system enough context to answer: what does this boundary protect, who owns it, and what would need to be true for us to change it?