OCI Architecture Decision Records (ADR): How Enterprise Teams Make Better Cloud Decisions

 

Introduction

Cloud architecture is full of decisions.

Some are obvious at the time. Others involve several technically valid alternatives, each with different implications for security, cost, availability, operations, and future growth.

The problem is that teams usually document what was implemented, but not necessarily why it was implemented that way.

Six months later, someone looks at an OCI environment and asks:

Why are we using Network Security Groups here?

Why was FastConnect selected instead of an IPSec VPN?

Why does this workload use a Service Gateway?

Why was this backup architecture selected?

Very often, the answer is buried in an old email, a meeting transcript, a ServiceNow ticket, a design document—or simply in the memory of the architect who made the decision.

That creates a subtle form of technical debt.

The architecture may be perfectly valid, but the reasoning behind it has disappeared.

This is where Architecture Decision Records (ADRs) become valuable.

An ADR doesn't need to be a 30-page architecture document. In fact, it should usually be the opposite: a concise record explaining the problem, the alternatives considered, the decision made, the reasoning behind it, and the consequences the team accepted.

For OCI environments, I see ADRs as a practical bridge between architecture, governance, and operations.

What Is an Architecture Decision Record (ADR)?

An Architecture Decision Record is a short document used to capture an important architectural decision and the context surrounding it.

A useful ADR should allow someone who was not present when the decision was made to understand the reasoning later.

For example, instead of documenting only:

NSGs will be used for application-tier security.

An ADR explains:

The environment requires security controls aligned with application roles rather than subnet membership. Security Lists and Network Security Groups were evaluated. NSGs were selected because they allow security rules to be associated directly with groups of VNICs and better support the workload segmentation model adopted for this environment.

That second version captures something much more valuable:

the reasoning.

A practical ADR normally records:

Context — What situation triggered the decision?

Problem — What are we trying to solve?

Options Considered — What realistic alternatives were evaluated?

Decision — What did we choose?

Rationale — Why?

Consequences — What benefits, limitations, risks, or operational responsibilities come with the choice?

Owner — Who is accountable for the decision?

Review Date — When should we verify that the decision still makes sense?

That final item is particularly important in cloud architecture.

An architectural decision that made sense two years ago may no longer be the best choice today.

Why Cloud Architecture Decisions Matter

When designing OCI environments, we rarely choose between a clearly correct option and a clearly incorrect one.

Usually, we choose between trade-offs.

Consider connectivity.

An IPSec VPN may satisfy a workload's connectivity requirements and provide a relatively straightforward implementation.

Another workload may justify FastConnect because its bandwidth, latency, traffic profile, or connectivity requirements are different.

Neither technology is automatically the correct answer without context.

The same applies across OCI:

Security Lists vs. Network Security Groups

Public connectivity vs. private service access

Balanced vs. higher-performance storage

Single-region vs. multi-region resilience

Standard logging vs. more advanced analytics

Manual operations vs. automation

Architecture therefore isn't simply:

“What OCI service should I use?”

A better question is:

“Which option best satisfies this workload's requirements, constraints, risks, and operational model?”

And once that question has been answered, the reasoning should survive beyond the meeting where the decision was made.

The Hidden Cost of Undocumented Decisions

I consider undocumented architecture decisions an operational risk.

Imagine that an engineer finds an apparently unnecessary component and removes it to simplify the environment.

Technically, the change looks reasonable.

What the engineer doesn't know is that the component was introduced eighteen months earlier to satisfy a security requirement, resolve a connectivity limitation, or support a disaster recovery scenario.

The configuration survived.

The knowledge didn't.

That is exactly the kind of situation ADRs can help prevent.

A good ADR repository provides historical context:

What did we decide?

Why did we decide it?

What alternatives did we reject?

What assumptions existed at the time?

What would cause us to reconsider the decision?

This becomes particularly valuable when environments are operated by multiple teams or handed over from architecture/project teams to operations.

Why ADRs Are Useful in OCI

I see five particularly useful applications for ADRs in enterprise OCI environments.

Technical Debt

An ADR can explicitly record that a decision is temporary.

For example:

IPSec VPN selected for initial deployment. Reassess FastConnect when production traffic exceeds the agreed threshold.

Without that record, a temporary solution can quietly become permanent architecture.

Knowledge Transfer

Engineers change teams.

Architects move to other projects.

Managed-service providers change.

The ADR keeps the architectural reasoning with the environment rather than with an individual.

Governance

Important architectural choices can be reviewed against organizational standards before implementation.

This is particularly useful for decisions involving IAM, networking, encryption, Internet exposure, logging, backup, and disaster recovery.

Compliance and Auditability

Where required, ADRs can provide supporting evidence explaining why a particular architectural control or implementation was selected.

Operational Consistency

Operations teams can understand not only the configuration but also the intent behind it.

That distinction matters during incidents and change management.

The OCI Architecture Decision Lifecycle

I don't see an ADR as something that should be written after everything has already been decided.

It should follow the decision itself.

The lifecycle I use conceptually is:

Request → Requirements → Evaluate Options → Decision → Implementation → Validation → Review → Retire or Update

Each stage has a purpose.

1. Request

A business need, technical problem, security requirement, operational issue, or architecture change triggers a decision.

For example:

Production workloads require private access to OCI services.

That becomes the decision request.

2. Requirements

Before comparing OCI services, define what the solution actually needs to accomplish.

This can include:

• Security requirements
• Availability requirements
• Performance expectations
• Cost constraints
• Compliance requirements
• Operational capabilities
• Recovery objectives

Skipping this stage often leads teams to choose technology first and justify it afterward.

3. Evaluate Options

Now we compare realistic alternatives.

Not every OCI service needs to be considered—only options that could reasonably satisfy the requirement.

For each option, I want to understand:

What does it solve well?

What does it complicate?

What does it cost?

What operational responsibility does it introduce?

What happens when it fails?

That last question is frequently overlooked.

4. Decision

Select the option that best satisfies the requirements.

The ADR should document not only the selected option but also why other viable alternatives were not selected.

5. Implementation

The approved decision becomes architecture.

Terraform, OCI Resource Manager, configuration procedures, change records, diagrams, and runbooks should reflect it.

6. Validation

This stage is critical.

The fact that something was successfully deployed does not prove that the architectural decision achieved its objective.

Validate the outcome.

If the objective was private connectivity, verify the actual network path.

If it was resilience, test failure.

If it was improved observability, verify that the expected telemetry is available.

7. Review

Architecture changes.

OCI evolves.

Business requirements evolve.

Therefore, important ADRs should be periodically reviewed or revisited when significant conditions change.

8. Retire or Update

An ADR should not be silently overwritten when the architecture changes.

Preserve the history.

Mark the previous decision as Superseded or Retired, and reference the new ADR.

That gives the organization an architectural timeline rather than just a snapshot.

OCI Architecture Decision Lifecycle

The OCI Architecture Decision Framework

For important OCI decisions, I use a simple principle:

Don't evaluate an option only by what it does well. Evaluate what adopting it means for the entire environment.

That means looking beyond functionality.

For this article, I created the JLTDS OCI Decision Score, which evaluates architectural options across seven dimensions.

Security

Does the option protect identities, workloads, network paths, and data appropriately?

Cost Efficiency

What is the expected cost across the lifecycle—not just the initial deployment?

Performance

Can it meet expected throughput, latency, IOPS, or workload requirements?

Availability

How does the option behave during component, availability-domain, or regional failures where applicable?

Scalability

Can the architecture grow without requiring significant redesign?

Operational Complexity

How difficult will the solution be to monitor, troubleshoot, patch, automate, and recover?

Maintainability

Can another engineer understand and support the design six months or two years from now?

Each dimension can be scored from:

1 — Very Poor

through

5 — Excellent

But there is an important rule:

The highest numerical score does not automatically determine the architecture.

A security-critical workload may give greater weight to Security.

A high-volume transactional workload may prioritize Performance and Availability.

A development environment may prioritize Cost Efficiency and simplicity.

The score supports the decision.

It doesn't replace engineering judgment.

A Practical ADR Structure

For the examples in this article, I recommend documenting each decision with the following structure:

Decision ID: ADR-XXXX

Title: Clear description of the decision

Status: Proposed / Accepted / Superseded / Retired

Context: Why is the decision required?

Requirements: What must the solution accomplish?

Options Considered: Which viable alternatives were evaluated?

Evaluation: Security, cost, performance, availability, scalability, operational complexity, and maintainability.

Decision: Which option was selected?

Rationale: Why was it selected?

Consequences: What do we gain, and what responsibilities or limitations do we accept?

Owner: Who owns the architectural decision?

Review Date: When should it be reassessed?

Related Artifacts: Architecture diagrams, Terraform, tickets, runbooks, policies, or related ADRs.

This is intentionally lightweight.

If creating an ADR becomes a bureaucratic exercise, engineers will stop creating them.

Architecture Decisions Need Context

Before moving into the examples, there is one principle I want to emphasize.

Suppose two OCI architects are asked:

Should we use FastConnect or an IPSec VPN?

Without additional information, neither should answer immediately.

We need context.

How much traffic?

What latency is acceptable?

What availability is required?

Is connectivity temporary or permanent?

What is the budget?

What does the on-premises network support?

What happens if the connection fails?

Does the organization already have FastConnect?

Only then does the technology discussion become meaningful.

That is why the first field in every ADR should not be:

Decision

It should be:

Context.

Part 2 — Architecture Decisions in Practice

Now that the framework is defined, let's apply it to decisions that commonly appear in OCI environments.

The objective of these examples is not to declare one OCI service universally better than another. Each ADR starts with a specific requirement, evaluates realistic alternatives, and records why a particular option makes sense for that context.

ADR-0001 — Security Lists vs. Network Security Groups

Context

An enterprise application is being deployed across multiple application tiers inside an OCI Virtual Cloud Network.

The environment contains web, application, and database components. Resources belonging to different application tiers may share subnets, but each tier requires different network security rules.

The architecture team needs to determine how network access rules should be organized.

Requirements

The design should:

• Apply least-privilege network access.
• Separate security rules by workload role.
• Remain manageable as the environment grows.
• Support application-centric segmentation.
• Avoid unnecessary duplication of rules.
• Allow future architectural changes without requiring major network redesign.

Options Considered

Option A — Security Lists

Security Lists provide network security rules associated with subnets.

This can work well when resources inside a subnet have similar security requirements.

The model is relatively straightforward:

Subnet → Security List → Rules → Resources

The challenge appears when workloads with different security requirements share the same subnet.

Option B — Network Security Groups

Network Security Groups allow security rules to be associated with groups of VNICs rather than applying them based solely on subnet membership.

This creates a more workload-oriented model:

Application Role → NSG → Security Rules

For example:

WEB-NSG

Allows HTTPS traffic from approved sources.

APP-NSG

Allows application traffic from the web tier.

DB-NSG

Allows database traffic only from the application tier.

The security model follows the workload rather than simply the network location.

Option C — Hybrid Approach

Security Lists and NSGs can also coexist.

Security Lists may provide broad subnet-level controls while NSGs implement more granular application-level rules.

This can be useful, but teams need clear ownership and documentation to avoid creating overlapping controls that become difficult to troubleshoot.

Decision

For this scenario:

Use Network Security Groups as the primary mechanism for application-tier network segmentation.

Security Lists can remain where subnet-level controls are required, but application-specific rules should primarily follow NSGs.

Why?

The main reason isn't that NSGs are automatically "better."

It is because the requirement is application-centric segmentation.

The web, application, and database tiers have different communication requirements even when network topology changes.

Associating controls with workload roles provides a clearer representation of the intended architecture.

Consequences

Positive

Security policies align more closely with application components.

Rules can remain associated with workloads even as subnet architecture evolves.

Least-privilege segmentation becomes easier to express.

The relationship between application tiers becomes easier to understand.

Operational Considerations

NSG naming and ownership need standards.

Unused NSGs should be reviewed and removed.

Changes should remain governed.

Troubleshooting procedures need to consider both NSGs and any applicable Security Lists.

This last point matters.

Adding NSGs does not eliminate the need to understand the complete network security path.

JLTDS Decision Perspective

For this scenario, NSGs would likely score strongly in:

Security — High

Scalability — High

Maintainability — High

Operational Flexibility — High

But the ADR should preserve the reason behind those scores rather than storing only a number.

ADR-0002 — Regional vs. AD-Specific Subnets

Context

A new application environment must be designed with resilience in mind.

The architecture team needs to decide whether subnet design should be tied to individual Availability Domains or span the region.

The Real Question

At first this can look like a networking decision.

But the real architectural question is:

Do we have a requirement that justifies binding this network construct to a specific Availability Domain?

That distinction changes the discussion.

Options Considered

Option A — AD-Specific Subnets

The subnet exists within a particular Availability Domain.

This can be appropriate when architecture or resource placement requires AD-specific network organization.

However, it also introduces stronger coupling between network design and physical resource placement.

Option B — Regional Subnets

Regional subnets are not restricted to a single Availability Domain.

This gives the architecture greater flexibility when resources are distributed across the region.

Decision

For a typical enterprise application where there is no explicit requirement for an AD-specific subnet:

Prefer regional subnets.

Rationale

The goal is to avoid introducing unnecessary infrastructure coupling.

If the application can distribute resources across availability boundaries, the network architecture should generally not create an artificial restriction without a clear reason.

This also makes future architecture changes easier.

Consequences

Positive

Greater placement flexibility.

Simpler network architecture.

Better alignment with architectures that distribute resources across the region.

Less dependency between subnet design and individual Availability Domains.

Considerations

Regional does not automatically mean highly available.

The application architecture still needs appropriate redundancy.

This is an important distinction:

A resilient subnet design cannot compensate for a non-resilient application design.

ADR-0003 — FastConnect vs. IPSec VPN

This is a good example of why ADRs need context.

There is no meaningful universal answer to:

“Which is better: FastConnect or VPN?”

The correct answer depends on the workload.

Context

An enterprise application running in OCI requires private connectivity to an on-premises data center.

The connection will support application integrations, administrative traffic, and data transfers.

Requirements

The architecture must consider:

• Expected bandwidth
• Latency sensitivity
• Availability
• Implementation timeline
• Cost
• Existing connectivity
• Operational support
• Redundancy requirements

Option A — IPSec VPN

An IPSec VPN provides encrypted connectivity across the Internet.

For many workloads, this can provide a practical way to establish private connectivity without dedicated connectivity infrastructure.

It can also be valuable for initial deployments or as part of a redundant connectivity design.

Advantages

Faster initial deployment in many scenarios.

Lower barrier to entry.

Encrypted connectivity.

Useful for moderate connectivity requirements.

Trade-offs

Traffic traverses Internet paths.

Performance characteristics may differ from dedicated connectivity.

Architecture still needs appropriate redundancy.

Option B — FastConnect

FastConnect provides dedicated private connectivity between customer networks and OCI.

It becomes particularly interesting when the workload has stronger requirements around bandwidth, predictable connectivity, or enterprise network integration.

Advantages

Dedicated connectivity model.

Supports higher-bandwidth enterprise scenarios.

Avoids relying exclusively on Internet paths for primary connectivity.

Can form part of a robust hybrid-cloud network architecture.

Trade-offs

More planning may be required.

Additional connectivity/provider considerations may exist.

Cost and operational complexity need evaluation.

Option C — Hybrid Connectivity

The architecture can use FastConnect as the primary path while maintaining VPN connectivity as part of the resilience strategy.

This introduces additional complexity but may be justified for business-critical environments.

Decision

For our hypothetical production environment with significant hybrid-cloud traffic:

FastConnect is selected as the primary connectivity method, with redundant connectivity designed according to the application's availability requirements.

The VPN option remains relevant for backup or other connectivity scenarios where appropriate.

Why?

Because the requirement isn't simply:

“Connect OCI to on-premises.”

It is:

“Provide production-grade connectivity appropriate for sustained enterprise workloads.”

That context changes the decision.

ADR-0004 — Service Gateway vs. NAT Gateway

Context

Application servers run in private subnets.

They need to access supported OCI services without requiring public IP addresses.

At the same time, selected workloads may also need outbound access to Internet destinations.

These are two different requirements and should not automatically use the same network path.

Option A — NAT Gateway

A NAT Gateway allows resources in private subnets to initiate outbound connections toward public destinations without assigning public IP addresses to those resources.

This is appropriate when the workload genuinely requires outbound Internet connectivity.

Option B — Service Gateway

A Service Gateway provides private access from a VCN to supported Oracle services without requiring traffic to traverse the public Internet.

For access to supported OCI services, this can provide a cleaner architecture than routing everything through Internet-oriented connectivity.

Decision

Use Service Gateway for private access to supported OCI services and NAT Gateway only where outbound Internet access is actually required.

This is not really a choice of one gateway over another.

They solve different problems.

Architecture Principle

This ADR produces a useful rule:

Don't create Internet-oriented paths for traffic that doesn't need the Internet.

That reduces unnecessary exposure and makes the intended network flows easier to understand.

ADR-0005 — Choosing the Right OCI Storage Model

Storage decisions are another area where asking:

“Which OCI storage service is best?”

is the wrong question.

The correct question is:

“What type of data access does this workload require?”

Context

An enterprise workload needs storage for three different purposes:

Application disks.

Shared application files.

Long-term backup and archive content.

Trying to solve all three requirements with one storage model would simplify the diagram but potentially create a poor architecture.

Block Volume

Appropriate when workloads require block-level storage attached to Compute instances.

Typical considerations include:

• Performance requirements
• Capacity
• Backup
• Resilience
• Cost
• Workload I/O profile

File Storage

Useful when multiple systems require shared filesystem-style access.

The architectural question becomes whether the workload actually needs shared file semantics rather than simply additional disk capacity.

Object Storage

Well suited to object-based data such as backups, exports, artifacts, logs, and other unstructured content depending on workload requirements.

Lifecycle management can also become an important part of the design.

Decision

For this environment:

Application disks → Block Volume

Shared application files → File Storage

Backups / long-term artifacts → Object Storage

The decision follows the access pattern rather than forcing all data into the same storage technology.

Lesson

Storage architecture should follow data behavior, not architectural convenience.

ADR-0006 — Standard Logging vs. Advanced Log Analytics

Context

The environment requires centralized operational visibility.

The team needs to determine whether standard OCI logging capabilities satisfy the requirement or whether more advanced log-analysis capabilities are justified.

Start With the Requirement

Before selecting a platform, ask:

What problem are we trying to solve with the logs?

If the requirement is primarily:

• Central collection
• Search
• Troubleshooting
• Retention
• Basic operational investigation

the solution may be different from an environment requiring:

• Large-scale correlation
• Advanced analytics
• Complex operational investigations
• Cross-system analysis
• Deeper pattern identification

Decision Approach

For a smaller or less complex environment:

Start with the simplest logging architecture that satisfies operational and compliance requirements.

For environments where log volume, correlation needs, operational complexity, or investigation requirements justify it:

Evaluate advanced analytics capabilities.

Why This ADR Is Different

Notice that this ADR doesn't declare one technology the winner.

The decision is based on complexity justified by requirements.

That is deliberate.

One of the easiest ways to create unnecessary cloud cost and technical debt is to deploy an advanced service simply because it exists.

The Architecture Principle Behind All Six Decisions

These six ADRs cover very different areas:

Security

Networking

Connectivity

Service Access

Storage

Observability

But they all lead to the same principle:

Architecture should be driven by requirements and trade-offs—not by service preference.

A cloud architect's job isn't to select the most sophisticated OCI service.

It is to select the architecture that appropriately balances:

Security

Cost

Performance

Availability

Scalability

Operational Complexity

Maintainability

for the specific business context.

OCI Decision Matrix

One Important Rule: Document Rejected Options

I would add one practice that is frequently overlooked.

Document why you didn't choose an option.

Suppose the ADR says:

Decision: FastConnect

Six months later someone may ask:

“Why don't we replace this with a VPN and reduce cost?”

If the ADR also records:

VPN was evaluated but not selected because the expected production traffic and connectivity requirements justified dedicated connectivity.

the organization doesn't have to restart the entire architectural discussion.

This is one of the biggest benefits of ADRs:

They preserve decisions that were already thought through.

Part 3 — From Individual Decisions to Architecture Governance

Architecture Decision Records become much more valuable when they stop being isolated documents and become part of the way architecture is governed.

Creating an ADR for one major network decision is useful.

Creating ADRs consistently for security, networking, identity, resilience, observability, automation, and cost decisions creates something different:

an architectural memory for the environment.

Over time, the repository starts answering questions that architecture diagrams alone cannot answer.

Why does this component exist?

Which alternatives were evaluated?

Which requirement drove the decision?

Who approved it?

What risks were accepted?

When should the decision be reviewed?

That history becomes particularly valuable when the people operating an environment are no longer the same people who originally designed it.

Common Architecture Decision Anti-Patterns

While working with enterprise environments, I have found that the problem is often not the absence of technical knowledge.

The problem is how architectural decisions are made, communicated, and preserved.

Several patterns deserve particular attention.

1. “This Is How We Always Do It”

Standards are valuable.

Blindly copying previous architectures is not.

A design that was appropriate for one environment may have been driven by very specific requirements.

Different workloads may have different:

Security requirements

Traffic patterns

Recovery objectives

Compliance obligations

Budgets

Operational capabilities

An existing architecture should be a reference—not an automatic answer.

2. Choosing the Service Before Understanding the Requirement

This is one of the easiest traps in cloud architecture.

The discussion starts with:

“We should use FastConnect.”

or:

“Let's implement Logging Analytics.”

But the requirement hasn't been defined yet.

Reverse the sequence.

Start with:

What problem are we trying to solve?

Then determine which OCI capability fits that problem.

3. Making Decisions Based Only on Cost

Cost matters.

But the cheapest architecture on a spreadsheet can become very expensive after an outage, security incident, performance issue, or months of manual operations.

Architecture cost should therefore include more than service pricing.

I would consider:

Infrastructure cost

Operational effort

Support complexity

Automation effort

Downtime exposure

Recovery complexity

Future migration cost

This is why Cost Efficiency is only one dimension of the JLTDS OCI Decision Score.

4. Ignoring Operations During Architecture Design

A design may look excellent in an architecture diagram and still be painful to operate.

Before approving a decision, I like asking:

How will we monitor it?

How will we patch it?

How will we troubleshoot it?

How will we back it up?

How will we recover it?

Who receives an alert when it fails?

Can the operations team actually support this design?

Architecture doesn't end when deployment succeeds.

That is when operations begins.

The “Day 2” Architecture Test

I use a simple mental test for important architecture decisions.

Instead of looking only at Day 1, imagine Day 2.

The solution has been running for twelve months.

The original architect isn't available.

An incident occurs at 02:00.

An engineer who did not design the environment has to understand it.

Can that engineer determine:

Why the architecture was designed this way?

Which dependencies matter?

What can safely be changed?

What should not be changed?

Where the recovery procedure is documented?

If the answer is no, the architecture may be technically correct but operationally incomplete.

Building an ADR Repository

Once ADRs become part of the architecture process, they need a home.

The specific platform matters less than consistency and accessibility.

A repository could live in:

Git

Confluence

SharePoint

An internal Wiki

Markdown-based documentation

or another governed knowledge platform.

The important point is that engineers should know exactly where architectural decisions are stored.

Building an ADR Repository

A Simple Repository Structure

One practical structure could look like this:

adr-repository/

├── 01-status/
│
├── 02-decisions/
│   ├── networking/
│   │   ├── ADR-0001-use-nsg.md
│   │   └── ADR-0003-fastconnect-vpn.md
│   │
│   ├── security/
│   │   └── ADR-0002-iam-groups.md
│   │
│   ├── resilience/
│   │   └── ADR-0004-dr-strategy.md
│   │
│   └── observability/
│       └── ADR-0005-logging-strategy.md
│
├── 03-templates/
│   └── ADR-template.md
│
├── 04-archives/
│
└── README.md

The structure doesn't need to be complicated.

In fact, simpler is usually better.

What matters is that someone joining the team can quickly discover:

what decisions exist, what is active, what has been superseded, and where to find the reasoning.

ADR Status Matters

I would avoid treating every ADR as permanently valid.

A simple lifecycle can use four states:

Proposed — The decision is still under evaluation.

Accepted — The decision has been approved and represents the current architecture.

Superseded — A newer ADR has replaced it.

Retired — The decision is no longer relevant.

Importantly, a superseded ADR should normally remain available.

Don't delete architectural history.

A decision that appears strange today may make perfect sense when viewed in the context of requirements that existed three years earlier.

Versioning and Governance

An ADR repository should preserve changes.

If Git is used, version control comes naturally.

If the repository lives in another platform, make sure change history is available.

For important decisions, I would also define:

Decision owner

Reviewers

Approval process

Review frequency

Related implementation artifacts

Superseding ADR

The objective is not bureaucracy.

The objective is traceability.

Connecting ADRs to Real Operations

This is where ADRs become especially useful.

An ADR should not live alone.

Where appropriate, connect it to the artifacts that implement or operate the decision.

For example:

ADR-0003 — FastConnect Connectivity Strategy

could reference:

Architecture diagram

Terraform module

Route configuration

Monitoring dashboard

Incident runbook

Disaster recovery procedure

Change record

Now the ADR becomes an entry point into the architecture rather than another document that nobody reads.

When Should an ADR Be Created?

Not every OCI configuration change deserves an ADR.

If every small technical action creates one, the repository becomes noise.

I would create an ADR when the decision:

significantly affects architecture;

introduces a meaningful security or operational trade-off;

is difficult or expensive to reverse;

affects availability or disaster recovery;

changes an enterprise standard;

introduces a major dependency;

requires future engineers to understand why it exists.

A simple configuration correction probably doesn't need an ADR.

Choosing the enterprise connectivity strategy probably does.

Architecture Decisions Should Expire

One practice I particularly like is assigning a review date to important decisions.

Not because every architecture decision needs to change, but because the assumptions behind it might.

For example:

ADR-0012 — IPSec VPN selected for initial OCI connectivity

At the time, traffic was limited.

Two years later:

• traffic has increased;
• more production systems depend on OCI;
• availability requirements have changed;
• the organization has expanded its cloud footprint.

The original decision may still be valid.

But now we have a reason to evaluate it again.

An ADR should capture not only:

“Why did we choose this?”

but sometimes:

“What conditions would make us reconsider it?”

That is a powerful architectural question.

Architecture Review: Turning ADRs Into Governance

The next step is connecting individual decisions to a broader architecture review.

Instead of reviewing an OCI environment only when there is a problem, teams can periodically evaluate the architecture across several domains.

For this article, I grouped the review into twelve areas:

1. Governance & Organization
2. Identity & Access Management
3. Networking
4. Security
5. Compute
6. Storage
7. Database Services
8. Backup & Disaster Recovery
9. Observability & Monitoring
10. Cost Management & FinOps
11. Automation & DevOps
12. Tagging & Resource Management

The objective isn't to generate a perfect score.

The objective is to expose decisions that may deserve another look.

OCI Architecture Review Checklist

From Checklist Finding to ADR

Suppose the architecture review identifies:

Cross-region recovery strategy has not been formally defined.

That should not necessarily become:

“Enable cross-region replication.”

That jumps directly from finding to technology.

Instead:

Finding

Cross-region recovery strategy is undefined.

↓

Requirement

The business requires a defined RTO and RPO for a regional disruption.

↓

Architecture Decision

Evaluate viable DR strategies.

↓

ADR

Document the selected strategy, alternatives, cost, operational impact, RTO/RPO assumptions, testing requirements, and consequences.

↓

Implementation

Deploy the approved architecture.

↓

Validation

Perform a DR test.

That is the difference between checking a box and governing architecture.

Using the JLTDS OCI Decision Score Responsibly

Earlier, I introduced seven dimensions:

Security

Cost Efficiency

Performance

Availability

Scalability

Operational Complexity

Maintainability

There is an important limitation to understand.

A decision score is useful for creating structured discussion.

It should never become:

“Option A scored 29 and Option B scored 27, therefore Option A wins.”

Architecture doesn't work that way.

Imagine:

Option A

Excellent cost, scalability, and maintainability—but unacceptable security.

Option B

More expensive and operationally complex—but satisfies a mandatory security requirement.

The total score is irrelevant.

A mandatory requirement can eliminate an option regardless of its numerical score.

Therefore, I would use the matrix in this order:

Mandatory Requirements

↓

Disqualify Non-Compliant Options

↓

Evaluate Remaining Alternatives

↓

Score Trade-offs

↓

Apply Engineering Judgment

↓

Document the Rationale

This distinction is important.

The matrix is a decision-support mechanism, not an architecture algorithm.

Architecture Is a Continuous Process

The lifecycle therefore doesn't really end at implementation.

A healthier model looks like:

Decide → Document → Implement → Validate → Operate → Observe → Review → Improve

Then, when requirements change:

Reconsider → New Decision → New ADR

This creates an architectural feedback loop.

The architecture learns from operations.

Operations preserve knowledge for architecture.

What Good Architecture Documentation Looks Like

Good documentation doesn't need to explain every resource in OCI.

It needs to preserve the information that would otherwise disappear.

For me, that means answering five questions:

What did we decide?

Why did we decide it?

What alternatives did we consider?

What consequences did we accept?

When should we reconsider it?

If an ADR can answer those five questions clearly, it is already providing significant value.

Final Thoughts

A good cloud architecture is important.

But a good architecture that nobody understands becomes difficult to maintain.

OCI provides us with an enormous range of capabilities for networking, identity, security, compute, storage, databases, observability, resilience, and automation.

The challenge isn't simply knowing that those services exist.

The harder part is deciding:

Which combination is appropriate for this environment, under these requirements, at this point in time?

And then preserving the reasoning.

That is why I see Architecture Decision Records as more than documentation.

They are a mechanism for technical memory.

They allow future engineers to understand the context behind today's architecture.

They help operations teams understand architectural intent.

They help reviewers challenge assumptions.

And they give organizations a structured way to revisit decisions as technology and business requirements evolve.

The goal is not to make perfect decisions.

Perfect information rarely exists.

The goal is to make decisions that are:

Deliberate.

Explainable.

Traceable.

Reviewable.

Adaptable.

Because sustainable cloud architecture isn't only about designing the right environment today.

It is also about ensuring that someone can understand why it was designed that way tomorrow.

About the Author

João Teixeira
Oracle ACE Apprentice
Oracle EPM & OCI Infrastructure Specialist

JLTDS Oracle Tech