Record an architectural decision and its assumptions

After inventory, threat modeling and responsibility allocation, a team needs an architecture decision it can implement and review. A box labeled “zero trust” between user and application is not a decision. State the issue operationally: where is access to a claim document decided and enforced, how is bypass prevented, and how does the decision change when user or service attributes change? List at least two feasible options and explicit constraints: service latency, ability to modify code, continuity when a decision component is unavailable and logging cost. Do not substitute a product name or fashionable technology for selection criteria. A useful record explains why a viable option was rejected, not only why the chosen option looks attractive.

One option enforces policy at an API gateway. It can standardize checks for requests crossing the gateway, but may not see the internal action a downstream service performs or a batch job's direct store connection. Another enforces inside the document service. That location sees the document identifier and claim relationship, but requires service changes and testing at every release. A combined design checks entry and enforces near the resource, reducing bypass while adding dependencies and operational work. If identities and attributes are unreliable, all three options can make the wrong decision consistently. Assign responsibilities explicitly: gateway checks requester session and broad constraints, service checks entitlement to the named document, and storage accepts only a narrowly scoped service identity.

Compare options using questions with concrete meanings rather than an unexplained total score. Can the point see the true resource identifier? Does every route cross it? Can it revoke access during a long session? What happens to reads and writes if it fails? Does it log a decision that can be joined to a business request? What is its maintenance burden as applications grow? Give evidence for each answer and an unknown requiring a trial. A condition in the user interface does not remove the need for storage permissions: another route may call the service. Use a small synthetic-data experiment when paper analysis cannot distinguish two options.

The record lists assumptions that may expire quickly: assignment data refresh within one minute, no legacy batch route directly reaches storage, and the service can evaluate document policy on every request. Give every assumption a test and owner. If actual assignment refresh takes fifteen minutes, preserving the old decision without review leaves transferred documents exposed to prior staff. A live check or a short lock after transfer may be needed. If an analytics platform has a direct route, close it or bring it into the protect surface. An architecture decision is not a certificate of permanent safety; it is an operational hypothesis bounded by evidence and reopening triggers.

Make rollout reversible: inventory paths, observe simulated decisions for a defined period, inspect legitimate denials, repair attribute feeds, enforce for a small cohort, expand under monitoring, then remove the old path. Set stop conditions such as a rise in denials of valid work, missing decision records or breached latency limits. Rollback must not mean opening every resource. Keep a narrower prior policy or a temporary approved manual route. During an incident, responders need to know which policy version made a decision and how to revoke one token without disabling the whole service. Bind the enforcement decision to versioned configuration and logs, not to team memory.

A compact decision table can make the comparison less vague. On resource visibility, the gateway is partial, the service is complete and storage sees an object key but may not know its business relationship. On path coverage, the gateway covers only routes through it, while service enforcement covers every call if direct storage access is removed. On change management, a gateway may be easier for a general condition, while the service is more precise for claim relationships but needs a release or policy engine. Both options require tests for unavailable attributes and decision components. Avoid saying one is universally “best”; identify which criterion settled this system's choice and why another system could decide differently.

A successful denial test is not automatically proof of the intended design. If the service rejects an unrelated claim because the document does not exist, it has not demonstrated the assignment rule. Test an existing document that is not assigned. If an expired partner is blocked only because the token expired first, the contract-status test is inconclusive. Design cases that isolate conditions: valid identity with unauthorized resource, valid resource with expired context, valid context through a direct route, and an unavailable decision component with legitimate work. Record the actual decision reason and version. These distinctions prevent a reassuring result from being credited to the wrong control.

Closure also needs agreement on later monitoring. The service owner reviews valid requests denied by mistake, security staff investigate repeated denials across many resources, and identity staff measure assignment-update delay. More recorded denial attempts do not automatically mean more attacks; enforcement may expose old access that previously passed without a record. Compare with the right denominator and consequence. If the business purpose changes, such as a new partner collaboration, revisit the protect surface and agreements instead of merely widening a role. The architecture then becomes an operable, correctable decision rather than a static diagram.