Documenting Architectural Assumptions and Risks

Good to see you again. In the last lesson, you mapped the flash-sale checkout system’s scope, containers, and trust boundaries. That gave the workload model a physical home: the Checkout API receives traffic, the Orders Database holds durable state, the payment queue absorbs provider disruption, and several interactions leave the system’s trust zone.

But each box and relationship in that diagram quietly depends on propositions that may not be true. Can the payment provider accept the intended traffic? Will the order store meet the two-second p99 acknowledgement target? Can a payment backlog survive a provider outage? This lesson makes such propositions explicit, connects each to a concrete risk, and turns uncertainty into validation work.

By the end, you should be able to maintain an architectural assumption log that answers four questions: what are we assuming, why does it matter, what happens if it is false, and how will we find out soon enough to act.

---

Assumptions are not requirements, decisions, or risks

An architectural assumption is a proposition treated as true for now because the architecture, plan, or quality goals depend on it. It is neither a mistake nor a sign of poor planning. Architecture necessarily begins before complete evidence is available. The mistake is to leave important assumptions implicit.

The distinctions below are worth keeping sharp.

Term	Meaning	Flash-sale checkout example
Requirement	A desired outcome or obligation	The system must durably acknowledge an eligible order within 2 seconds at p99.
Constraint	A fixed limit imposed on the solution	Payments must use the selected external provider.
Decision	A chosen approach among alternatives	Accept orders durably, then process payment work asynchronously.
Assumption	Something believed true but not sufficiently confirmed	The payment provider account will accept the required request rate.
Risk	An uncertain event and its consequence	Provider throttling creates a growing backlog and delays order confirmation.
Fact	Something supported by current evidence	A load test recorded 200 sustained requests per second in the target environment.

The central relation is simple:

An assumption creates architectural risk when its being false could prevent a stakeholder goal or quality-attribute scenario from being met.

This ties directly to the earlier scenario:

During a flash sale, the system must accept eligible orders at 200 requests per second, handle a 300 requests-per-second opening burst, and durably acknowledge each accepted order within 2 seconds at p99.

Suppose the design assumes that the Orders Database can make durable commits at that rate. If the assumption is false, the system may miss the acknowledgement target. The resulting risk is not merely “the database might be slow.” It is a threat to a measurable business and user outcome: customers may abandon checkout, support volume may rise, and the sale may lose revenue.

A useful assumption is therefore specific, scoped, and falsifiable.

Too vague	Usable architectural assumption
“The database will scale.”	“The Orders Database can durably commit the expected 200 requests per second and the 300 requests-per-second opening burst while the Checkout API keeps acknowledgement latency below 2 seconds at p99.”
“The payment provider is reliable.”	“The provisioned payment-provider account accepts the expected authorisation workload without account-level throttling and meets the agreed response-time objective.”
“The queue has enough capacity.”	“The payment-work queue retains at least 180,000 pending work items without loss and supports recovery while normal traffic continues.”
“Internal services are trusted.”	“Only the Payment Worker workload identity can read payment work and invoke the payment-provider integration.”

The final example shows why the trust boundaries in your container diagram matter. A line crossing from the Payment Worker to a third-party provider is not only an integration relationship. It carries assumptions about identity, credentials, permitted data, provider behaviour, and operational responsibility.

Where assumptions hide

Use the artifacts you already have to uncover assumptions systematically:

• Quality-attribute scenarios reveal assumptions about latency, throughput, durability, availability, security, and recovery.
• Workload models reveal assumptions about traffic shape, data growth, concurrency, and outage backlog.
• Context and container diagrams reveal assumptions at every external dependency, data store, and trust-boundary crossing.
• Vendor contracts and platform documentation reveal assumptions about quotas, regional availability, retention, support obligations, and feature semantics.
• Team plans reveal operational assumptions: on-call coverage, specialist availability, deployment permissions, and the ability to observe failures.

A productive prompt in an architecture review is:

“What would have to be true for this design to meet its stated quality scenarios?”

That wording is better than asking, “What could go wrong?” because it starts from a specific architectural claim rather than an unbounded list of anxieties.

---

Turn a hidden proposition into a risk statement

An assumption should be documented in its own right, but it becomes useful only when paired with its failure mode. Write the risk as a conditional chain:

1. Context: under what operating conditions does the assumption matter?
2. Condition: what does it mean for the assumption to be false?
3. Technical effect: what concretely occurs in the system?
4. Stakeholder consequence: which quality goal, business outcome, or obligation is harmed?

For example:

Assumption: The payment-work queue can retain the backlog from a 15-minute payment-provider outage.

Risk if false: During a 15-minute payment-provider outage at 200 accepted orders per second, if the queue cannot retain or recover approximately 180,000 pending payment tasks, payment work may be rejected or lost. Orders can remain unresolved, and reconciliation effort and customer-support demand can rise substantially.

The backlog estimate follows from the workload model:

$$200\text{ orders per second}\times 15\text{ minutes}\times 60\text{ seconds per minute}=180,000\text{ orders}$$

Notice the discipline in this statement:

• It names a context, rather than implying that capacity is infinite.
• It describes a falsifiable condition, rather than saying “the queue has problems.”
• It names a system effect that engineers can detect.
• It states a business and operability consequence, rather than stopping at a component-level symptom.

One assumption may produce more than one risk. For instance, an assumption that product-price data is fresh at checkout can affect revenue integrity, customer trust, refund volume, and legal compliance. In a log, it is acceptable to link one assumption to multiple risk entries if the consequences need different owners or mitigations.

---

Build an assumption log that drives action

The following template is deliberately compact. It can live in an architecture repository, issue tracker, or lightweight decision register, provided that it has an owner and is reviewed.

Field	Purpose
ID	Gives the assumption a stable reference, such as ASM-03.
Category	Helps select validation methods: workload, technical integration, data, security, operational, legal, or organisational.
Assumption statement	States precisely what is currently believed.
Evidence and confidence	Records why the team believes it and how strong that evidence is.
Risk if false	Captures the context, technical failure, and stakeholder consequence.
Likelihood and impact	Prioritises validation and mitigation work.
Validation method and success criterion	States how the team will confirm or refute it.
Owner and due date	Makes follow-up accountable and time-bound.
Status	Tracks whether the item is proposed, under test, confirmed, revised, refuted, or obsolete.
Links	Connects to scenarios, diagrams, tests, incidents, and eventually decision records.

The key field is evidence. “The vendor documentation says it should work” is evidence, but often weak evidence for an account-specific production quota, a peak-load behaviour, or an end-to-end latency target. Evidence becomes stronger when it comes from a representative experiment, a contractual commitment, an observed production measurement, or a review by the party responsible for the constraint.

Example: an initial flash-sale assumption log

At this stage, the entries are not claims that the design is safe. They are a visible backlog of architectural learning.

ID	Assumption	Risk if false	L	I	Validation and owner
ASM-01	The Orders Database can durably commit the expected sustained and burst workload within the 2-second p99 acknowledgement target.	Checkout acknowledgements exceed the quality target or time out during the sale, causing abandoned orders and loss of revenue.	2	3	Run a representative load test with realistic order size, indexes, durability settings, and burst pattern. Owner: platform engineer.
ASM-02	The provisioned payment-provider account accepts the intended authorisation rate without throttling.	Payment work accumulates faster than it can be processed; confirmation is delayed and reconciliation work rises.	3	3	Confirm account-specific quotas and run a provider-approved integration test. Owner: payments lead.
ASM-03	The payment-work queue can retain at least 180,000 pending items and drain the backlog while normal traffic continues.	Payment tasks are rejected, expire, or are lost; orders remain unresolved.	2	3	Verify retention and storage limits, then test sustained enqueueing and recovery drain rate. Owner: messaging engineer.
ASM-04	Existing shopper tokens remain verifiable during a brief Identity Provider disruption.	Legitimate shoppers cannot place orders even though the Checkout API and database are healthy.	2	3	Test key caching, token-expiry handling, and behaviour when the identity endpoint is unavailable. Owner: security engineer.
ASM-05	The email provider may process the minimum necessary customer contact and order-status data in the intended operating regions.	Order notifications are delayed or the system violates privacy or contractual obligations.	2	3	Review the data flow, provider agreement, and regional processing commitments. Owner: privacy or compliance owner.

Here, likelihood $L$ and impact $I$ use a three-level scale:

• $1$: low
• $2$: medium
• $3$: high

A quick exposure score is:

$$E=L\times I$$

On this scale, ASM-02 has an exposure score of $9$, while ASM-01 has a score of $6$. That does not mean the database risk can wait indefinitely. It means the payments integration should be investigated first, especially because payment capacity depends partly on a third party and affects a high-visibility sale event.

Do not treat scores as measurements of reality. They are a structured basis for comparison and discussion. A team should use one scale consistently; mixing a three-level matrix with a ten-level matrix produces numbers that look precise but cannot be meaningfully compared.

---

Validation, mitigation, and reversibility are different responses

A frequent failure mode is to document a risk, assign it a score, and call that risk management. The purpose of the log is to change the architecture or reduce uncertainty before the consequence occurs.

There are three distinct responses.

Validate the assumption

Validation asks whether the proposition is actually true. It should have a clear success criterion.

For ASM-01, “test database performance” is not sufficient. A useful validation criterion might be:

With representative order payloads and production-equivalent durability settings, the Checkout API acknowledges 99 percent of eligible order submissions within 2 seconds under 200 sustained requests per second and a 300 requests-per-second opening burst.

A test may confirm the assumption, refute it, or reveal that it needs revision. All three outcomes are valuable. If the test shows a p99 of 2.8 seconds, the assumption is not “a little confirmed”; it is refuted relative to the stated scenario.

Mitigate the consequence

Mitigation reduces the likelihood or impact even if the assumption proves false.

For payment-provider throttling, possible mitigation directions include:

• applying a rate limit that respects the provider’s confirmed quota;
• retaining payment tasks durably and exposing a clear payment pending order state;
• monitoring queue age and depth so the team detects delayed confirmation before the backlog becomes unrecoverable;
• defining customer communication and reconciliation procedures for long-running pending orders.

These are directions, not automatic design choices. Later modules will examine rate limiting, queues, retries, backpressure, and graceful degradation in detail. For now, the architectural point is that a mitigation should be linked to a stated failure consequence.

Preserve the ability to change course

Sometimes the team cannot validate an assumption early enough, or validation is expensive. In that case, the architecture should avoid making the uncertain choice expensive to reverse.

For example, isolating payment-provider-specific request mapping, credentials, and webhook handling behind a narrow integration boundary does not eliminate provider risk. It does reduce the cost of adapting to a quota change, different failure semantics, or a future provider replacement.

This is not an argument for abstracting everything. Flexibility has a cost: extra interfaces, test surface, operational complexity, and cognitive load. Spend that cost where uncertainty is material and the consequence of being wrong is substantial.

---

Prioritise by exposure, decision timing, and reversibility

The simple exposure score helps, but prioritisation should also consider when the decision becomes expensive to change.

A low-likelihood assumption can deserve immediate attention when it has irreversible consequences. Examples include:

• a regional data-processing obligation discovered after data has been stored in a prohibited location;
• a retention policy that cannot support required audit evidence;
• a public API contract released before compatibility expectations are understood;
• a data partitioning choice that later creates a concentrated, unmovable tenant.

Conversely, a moderately likely issue may be safely deferred when the architecture contains it behind a small boundary and a low-cost replacement path exists.

Use this ordering rule:

1. Address assumptions with high stakeholder impact and a near-term point of irreversibility.
2. Validate assumptions whose result would materially change the chosen architecture.
3. Mitigate high-impact risks that cannot be validated before delivery.
4. Explicitly accept lower-exposure risks only with a review date, trigger, and named owner.

The following short video demonstrates risk scoring against an architectural quality attribute. Its example concerns elasticity in an assessment system, but the reasoning transfers directly to checkout throughput and queue-capacity risks.

---

Assumption management is a continuous architectural activity

Assumptions have a lifecycle. They are made, described, evaluated, maintained, and occasionally retired. A confirmation is never necessarily permanent: a changed workload, new region, vendor contract, data set, or deployment topology can invalidate previously sound evidence.

The process begins with uncertainty from individuals and teams, but it needs project evidence to become a well-formed architectural risk.

The CMU Software Engineering Institute places this work in a continuous development context rather than treating it as an activity reserved for an initial architecture workshop.

A practical cadence for the checkout system might be:

• During backlog refinement: identify assumptions embedded in new stories, acceptance criteria, provider integrations, and quality scenarios.
• During sprint planning: create validation work as a spike, test, prototype, contract review, or operational task; give it an owner and due date.
• During design review: revisit assumptions affected by changed diagrams, workload numbers, dependencies, or trust boundaries.
• During sprint review and operations: update confidence using measurements, incidents, test results, and stakeholder feedback.
• Before major release points: review the unresolved high-exposure assumptions explicitly with the people accepting the associated business risk.

Keep the log connected to the architecture rather than detached in a spreadsheet. For example:

• ASM-02 can link to the Payment Worker to Payment Provider relationship in the container diagram.
• ASM-03 can link to the payment queue and the provider-outage workload scenario.
• ASM-04 can link to the public-client and identity trust boundary.
• A later architecture decision record can cite the assumptions that justified a decision and the conditions that should cause reconsideration.

A good review question is not, “Is the assumption still open?” It is:

“What evidence would change our design, and have we obtained it?”

If the answer is “we do not know,” the assumption remains active regardless of how long it has been in the log.

---

Key takeaways

Architectural assumptions are unavoidable working hypotheses; undocumented assumptions are hidden sources of risk. State them precisely enough to be tested, and distinguish them from requirements, decisions, constraints, and facts.

For every material assumption, document the consequence if it is false. Connect that consequence to a measurable quality scenario, a business objective, a trust boundary, or an operational obligation. A risk statement should describe context, failure condition, system effect, and stakeholder impact.

Maintain a living assumption log with evidence, likelihood, impact, validation criteria, an owner, a due date, and links to the relevant architectural artifacts. Prioritise not only by likelihood and impact, but also by irreversibility and the cost of being wrong.

Next, you will compare candidate architectures through a trade-off matrix covering performance, availability, security, operability, cost, and evolvability. The assumptions and risks documented here will provide the evidence base for that comparison.