Decision documents fix that. Call them ADRs, RFCs, or decision logs — the label doesn’t matter. What matters is writing down the context, the options, and the reasoning at the moment of the choice. Running a dev team this year has made me appreciate them more than ever: they’re the difference between institutional memory and institutional folklore.

Why they’re worth the effort

#

The obvious payoff is not having the same argument twice. “Didn’t we already decide on the API versioning strategy?” With a clear record of what was decided and why, settled issues stay settled and the team spends its energy on execution instead of retracing its steps.

The quieter payoff shows up over time. Projects run for months or years, people join and leave, and what survives is the code — which tells you what was decided but never why. A decision doc preserves the reasoning: the constraints that existed, the alternatives that were rejected, who made the call. New joiners get context instead of folklore. Cross-team decisions get real buy-in, because everyone can see the factors being weighed rather than just the verdict. And naming a decision-maker and contributors means follow-through has an actual owner.

When to write one

#

Not every decision deserves a document. I reach for one when the decision is:

• Expensive to reverse — technology stack choices (frameworks, databases, cloud providers), architectural patterns (microservices vs. monolith, event-driven vs. request-response), third-party vendors, security and compliance approaches
• Long-lived — API contracts that external systems depend on, data models that span services, breaking changes to established patterns
• Cross-team — anything needing buy-in from multiple teams or non-technical stakeholders, resource allocation and prioritisation calls
• The outcome of a spike — when a time-boxed investigation wraps up, capture the findings and the resulting decision before they evaporate

Skip the formality for easily reversible decisions, team-internal implementation details, and anything with minimal impact outside your immediate scope. A document nobody needed is just homework.

The lifecycle

#

┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   Draft     │ ──► │   Review    │ ──► │  Approved   │ ──► │ Implemented │
│  Proposed   │     │  Feedback   │     │  Accepted   │     │  Completed  │
└─────────────┘     └─────────────┘     └─────────────┘     └─────────────┘
                           │
                           ▼
                    ┌─────────────┐
                    │  Rejected/  │
                    │  Superseded │
                    └─────────────┘

The author drafts the problem and the candidate solutions. Stakeholders review — this is the phase that earns the whole exercise, because it’s where assumptions get challenged and blind spots surface. A decision-maker (usually a tech lead, architect, or product owner) makes the final call, the team implements, and the doc gets updated if reality forced changes along the way. Some documents die in review; others get superseded later as circumstances change. Mark both clearly, because a stale “accepted” doc is a trap for whoever finds it next.

What makes one worth reading

#

Start with the problem, not your favourite solution. What are we solving, why does it matter now, and what happens if we do nothing? If people don’t agree on the problem, debating solutions is theatre.

Then present real options — at least two or three, even when you have a strong preference. For each one: a brief description, pros and cons, a rough effort estimate (T-shirt sizing is fine: S/M/L/XL), and the risks with how you’d mitigate them. Documenting the alternatives is how future readers understand why the winner won.

Name the trade-offs out loud. “We’re choosing speed-to-market over architectural purity.” “We’re accepting increased operational complexity for better scalability.” “We’re prioritising developer experience over raw performance.” Sentences like these do more for a future reader than pages of analysis.

Ground the discussion in something concrete: code snippets showing how a solution would look, diagrams of the system interactions, links to proof-of-concept work from spikes. Abstract discussions produce abstract decisions.

Finally, give it a deadline — when the decision must be made, who owes input by when, and what’s blocked while it drifts. Decisions without deadlines drift forever.

Example: Architecture Decision Record (ADR)

#

Here’s a practical example of a decision document:

# ADR-001: API Authentication Strategy

**Status:** Accepted
**Date:** 2024-11-15
**Decision Maker:** Sarah Chen (Platform Architect)
**Contributors:** Backend Team, Security Team, Mobile Team

## Context

Our public API currently uses API keys for authentication. As we expand to
support third-party integrations and mobile apps, we need a more robust
authentication mechanism that supports:
- Token expiration and refresh
- Scoped permissions
- User-level authentication (not just service-level)

## Decision

We will implement OAuth 2.0 with JWT tokens for API authentication.

## Options Considered

### Option 1: OAuth 2.0 with JWT (Recommended)
**Description:** Industry-standard protocol with self-contained tokens

| Pros | Cons |
|------|------|
| Industry standard, well-documented | More complex initial implementation |
| Self-contained tokens reduce database lookups | Tokens cannot be revoked instantly |
| Broad library support | Requires refresh token management |

**Effort:** Medium (2-3 sprints)

### Option 2: Session-based Authentication
**Description:** Traditional server-side sessions with cookies

| Pros | Cons |
|------|------|
| Simple to implement | Not suitable for mobile apps |
| Easy to revoke sessions | Requires sticky sessions or shared session store |
| Familiar to most developers | Doesn't scale as well |

**Effort:** Small (1 sprint)

### Option 3: Custom Token System
**Description:** Build our own token-based authentication

| Pros | Cons |
|------|------|
| Fully customizable | Reinventing the wheel |
| No external dependencies | Security risks from custom implementation |

**Effort:** Large (4+ sprints)

## Consequences

- Mobile team can implement standard OAuth flows
- We'll need to set up a token refresh mechanism
- API documentation will need updates for OAuth flows
- Existing API key users will need a migration path (6-month deprecation)

## References

- [OAuth 2.0 RFC 6749](https://tools.ietf.org/html/rfc6749)
- Internal spike document: [Authentication Options Spike](/spikes/auth-spike-2024)
- Security team review: SEC-2024-042

A template to steal

#

Use this as a starting point and trim it to fit your team:

Problem Statement

#

What problem are we solving? Why does it matter? What’s the cost of inaction?

Background

#

Provide context, history, and any relevant details. Link to related documents, previous decisions, or spike results.

Constraints

#

What limitations or requirements must any solution respect?

• Budget constraints
• Timeline requirements
• Technical constraints (existing systems, skill sets)
• Compliance or security requirements

Solutions Considered

#

Recommendation

#

State your recommended option and summarize why it’s the best choice given the constraints and trade-offs.

Decision

#

Document the final decision once made. If different from the recommendation, explain why.

Consequences

#

What are the implications of this decision? What follow-up work is required?

Action Items

#

References

#

Links to related documents, external resources, spike results, or prior decisions.

Making the habit stick

#

Store the docs somewhere consistent — a dedicated folder in the repo, a wiki space — because a decision nobody can find might as well not exist. Keep them lightweight; a document that takes days to write won’t get written. Reference them from code comments, commit messages and pull requests, so the “why” stays attached to the “what”. When a decision is superseded, don’t delete the old doc — mark it superseded and link to the new one; the history is the point. And revisit old decisions in your retrospectives: which ones held up, which you’d make differently now.

The failure modes are just as predictable. Analysis paralysis: set a deadline, decide with the information you have, and remember most decisions can be revisited. Rubber-stamp reviews that never produce real critique add process without adding value. Orphaned documents that never lead to action are worse than no documents at all. Too much detail: the doc should cover the why and the what, not the how — implementation belongs in technical specs. And when stakeholders disagree, write the dissent down. The decision may stand anyway, but the objection is exactly the context someone will need a year from now.

Start with your next significant decision. Write it up, even if it’s rough, and refine the process as you go. Every “why did we choose X?” meeting that doesn’t happen because someone just read the ADR is an hour your team gets back.

Further Reading

#

Related Articles on This Site:

• Understanding Spikes in Agile Software Development - gather information with a spike before making the big call
• Retrospectives: The Power of Feedback Loops - review past decisions as part of continuous improvement
• Planning an API - decision-document thinking applied to API design
• GitHub for Project Management - keep decision documents next to your code

External Resources:

• Documenting Architecture Decisions - Michael Nygard - the original post that popularised ADRs
• ADR GitHub Organization - tools, templates and examples for Architecture Decision Records
• Design Docs at Google - how Google approaches design documentation
• RFC Process at Rust - a well-documented RFC process from the Rust language
• Spotify’s Decision Record Template - Spotify’s take on when to write an ADR

Every B2B SaaS runs into the tenancy question eventually, usually the day a big prospective customer asks whether their data can live somewhere separate from everyone else’s. I’ve been near this conversation at more than one company now, and the answer always comes down to two options: give each customer their own instance (single-tenant, multi-instance), or run everyone on one shared instance (multi-tenant, single-instance). Neither is “correct”. They just fail in different ways.

Infrastructure Design

#

Single tenant, multi-instance

#

The appeal here is isolation, and nearly every benefit flows from it. Each customer’s data sits in its own environment, so security reviews and compliance conversations get a lot easier. A bad deploy or a heavy workload takes down one customer instead of all of them. You can scale, tune, and customise each instance independently, and dedicated resources mean nobody’s performance depends on what a neighbouring tenant is doing. Maintenance can be scheduled per customer, which keeps downtime small and targeted, and if you price things sensibly you can match infrastructure cost to what each tenant actually uses.

The price you pay is that you’re now running N copies of everything. Resource overhead adds up, configuration drifts between instances, and keeping versions and data in sync across the fleet becomes its own project. Scaling, isolation, and cost management still need real planning. The problems don’t disappear; they multiply.

Multi tenant, single instance

#

This is the default for a reason: one deployment, one database to back up, one version in production. It’s efficient with resources, simple to operate, and every customer gets updates and security patches at the same moment.

The hard parts are the flip side of sharing. One tenant’s heavy usage can drag down everyone’s performance, per-customer customisation is limited, and data isolation now lives in your application code rather than your infrastructure, so a single bug can turn into a cross-tenant data leak. Scalability bottlenecks hit all customers at once, and maintenance needs more care because there’s no “just this customer” blast radius anymore.

Learn more about SaaS Solutions - Multi-instance vs. Multi-tenant Architectures

Multi-tenant vs multi-instance

#

You’ll often see this described as multi-tenant vs multi-instance instead, and it’s the same choice seen from the other side. “Tenant” is about customers: how many share one copy of the software. “Instance” is about deployments: how many copies you run. A single-tenant product is a multi-instance deployment, one copy per customer, and a multi-tenant product is usually a single instance that everyone shares. So when someone asks for multi-instance, they’re asking for single-tenancy.

In practice it’s a range rather than two boxes, and most of the real decisions are about the database. At the most shared end, every customer’s rows sit in the same tables with a tenant_id column, and every query filters on it. That’s the cheapest to run and the easiest to get wrong. One step along, each customer gets their own schema inside a shared database, which gives you cleaner separation and per-customer backups, at the cost of running every migration once per schema. Further along, the application stays shared but each customer gets their own database: a popular middle ground, with strong data isolation and no need to run a whole stack per customer. At the far end is full single-tenancy, with the application and the database both dedicated. AWS’s SaaS guidance calls the two ends silo and pool, and mixes of the two bridge, which is handy vocabulary when you’re explaining your setup to a customer’s security team.

Single-tenant vs multi-tenant at a glance

#

When to use which

#

Go multi-tenant unless something specific pushes you off it. It’s the right default when you have lots of customers paying modest amounts, when people sign themselves up, and when your team is small enough that thirty environments would eat it alive.

Single-tenant earns its overhead in a few situations. Customers in health, finance and government often need their data physically separate, or kept in a particular country, and a dedicated instance is the simplest honest answer to that in a security review. A handful of large customers on enterprise contracts can carry the cost of their own stack, and often expect one. And when customers need their own release schedule, a pinned version or deep customisation, separate instances stop being overhead and become part of what you’re selling.

Where most teams end up is both: a multi-tenant product for nearly everyone, and a dedicated instance as an enterprise tier for the few customers who need it and will pay for it. If the multi-tenant version carries a tenant ID everywhere from day one, moving one customer out to their own database later is a migration rather than a rewrite.

Making multi-tenant isolation harder to break

#

The multi-tenant bug that keeps people up at night is the query that forgets its tenant filter. It doesn’t fail. It quietly returns somebody else’s data, and code review won’t catch every one. If you’re on Postgres, row-level security moves the check into the database, so a query that forgets the filter still only sees the current customer’s rows:

ALTER TABLE invoices ENABLE ROW LEVEL SECURITY;

CREATE POLICY tenant_isolation ON invoices
    USING (tenant_id = current_setting('app.tenant_id')::uuid);

Each request then sets its tenant inside a transaction with SET LOCAL app.tenant_id = '…', so a pooled connection doesn’t carry one customer’s ID into the next request, and a request that never sets it gets an error rather than rows. Two catches: connect the app as a role that doesn’t own the table, because owners skip these policies unless you also add FORCE ROW LEVEL SECURITY, and never as a superuser, which skips them regardless.

Where to start for single-tenant?

#

If you do go single-tenant, tooling decides whether it’s manageable or a slow-motion disaster. You can’t hand-manage thirty environments.

The core is containers plus infrastructure as code. Docker packages the app identically for every tenant, Kubernetes handles deploying and scaling all those instances, and Terraform, Pulumi, or AWS CloudFormation let you define a tenant’s entire stack in code, so spinning up customer #31 is a pull request rather than a lost weekend. If you’re living closer to the VM world, configuration management tools like Ansible, Chef, or Puppet fill the same role. A solid CI/CD pipeline (Jenkins, GitLab CI/CD) matters more than usual here, because every release has to roll out across every instance without babysitting.

Beyond that, it depends on your product’s shape. Serverless (AWS Lambda, Azure Functions) can remove the server layer entirely for some workloads. Managed databases like Amazon RDS or Azure SQL Database save you from administering one database per tenant by hand. Monitoring with Prometheus, Grafana, or New Relic stops being optional once you have a fleet, because you want to know which instance is unhappy before the customer tells you. For identity, a service like Auth0 or Okta handles user management and access control without you rebuilding it per tenant. Whatever language you work in, there’s probably a SaaS-oriented framework or library that saves you some of this plumbing, and any of the big clouds (AWS, Azure, Google Cloud Platform) will host all of it happily.

Don’t buy the whole list on day one. Start with containers and IaC, add monitoring and IAM as tenants accumulate, and let actual pain drive the rest.

The short version

#

Single-tenant, or multi-instance, means a separate copy of the application and database for each customer: strong isolation and per-customer control, and a fleet to run. Multi-tenant means one shared copy: cheap and simple, with isolation enforced in code. Most products should start multi-tenant, with a tenant ID on everything and the database enforcing it, and offer dedicated instances to the few customers who need them and will pay for them. If you do run single-tenant, containers and infrastructure as code are what keep it manageable.