Skip to content

Decision Records Process

This document describes the process for creating and maintaining Architecture Decision Records (ADRs) and Business Decision Records (BDRs). It is written for architects, engineers, and product managers making important decisions.

ConnectSoft uses ADRs and BDRs to document important decisions, their context, and rationale. Decision records provide traceability, clarity, and alignment across teams. They're living documents that evolve as decisions change.

Decision

ConnectSoft uses Architecture Decision Records (ADRs) for technical decisions and Business Decision Records (BDRs) for business decisions. All decisions are documented, versioned, and stored in the docs/decisions/ directory. See BDR-0001: Generated Code Ownership for an example.

Why We Use ADRs and BDRs

Traceability

  • Decision history - See why decisions were made
  • Context preservation - Understand context and constraints
  • Evolution tracking - Track how decisions evolved over time

Clarity

  • Clear rationale - Document why a decision was made
  • Alternatives considered - See what options were evaluated
  • Trade-offs - Understand pros and cons of each option

Alignment

  • Shared understanding - Everyone understands decisions
  • Consistency - Decisions align across teams
  • Onboarding - New team members understand decisions quickly

When to Create a Decision Record

Architecture Decisions (ADRs)

Create ADR when:

  • Technology choices - Choosing frameworks, databases, messaging systems
  • Architectural patterns - Deciding on patterns (microservices, event-driven, etc.)
  • Integration approaches - How services integrate
  • Infrastructure decisions - Deployment targets, scaling strategies
  • Breaking changes - Changes that affect multiple services

Examples: - "Use Cosmos DB for event storage" - "Implement event sourcing for Audit Platform" - "Use Azure Service Bus for messaging"

Business Decisions (BDRs)

Create BDR when:

  • Business model changes - Pricing, licensing, business models
  • Product decisions - Feature priorities, product direction
  • Code ownership - IP ownership, licensing decisions
  • Compliance decisions - Security, privacy, regulatory decisions
  • Strategic choices - Long-term strategic decisions

Examples: - "Customers own generated code" - "SaaS-first business model" - "Domain strategy (.ai, .io, .dev)"

When NOT to Create

Don't create for:

  • Temporary decisions - Decisions that will change soon
  • Obvious choices - No real alternatives considered
  • Implementation details - Low-level implementation choices
  • Minor changes - Changes that don't affect architecture or business

Structure of an ADR/BDR

ADR Structure

Template:

# ADR-XXXX: Title

## Status
[Proposed | Accepted | Deprecated | Superseded]

## Context
[Background and context]

## Decision
[What we decided]

## Consequences
[Positive and negative consequences]

## Alternatives Considered
[Other options evaluated]

## Notes
[Additional notes, links, etc.]

BDR Structure

Template:

# BDR-XXXX: Title

## Status
[Proposed | Accepted | Deprecated | Superseded]

## Context
[Business context and background]

## Decision
[What we decided]

## Rationale
[Why this decision was made]

## Business Impact
[Impact on business, customers, revenue]

## Alternatives Considered
[Other options evaluated]

## Notes
[Additional notes, links, etc.]

See: BDR Template for complete template.

Workflow for Creating and Approving Decisions

Creating a Decision Record

Steps:

  1. Identify Decision - Recognize that a decision needs to be documented
  2. Create Draft - Create ADR/BDR file in docs/decisions/adr/ or docs/decisions/bdr/
  3. Fill Template - Complete all sections of template
  4. Set Status - Mark as "Proposed"
  5. Create PR - Create PR with decision record

Reviewing Decisions

Review Process:

  1. Architecture Review - Senior architects review ADRs
  2. Business Review - Product/business team reviews BDRs
  3. Team Review - Relevant teams review decisions
  4. Feedback - Collect feedback and update decision
  5. Approval - Approve decision and update status to "Accepted"

Decision Lifecycle

Statuses:

  • Proposed - Decision is proposed, under review
  • Accepted - Decision is accepted and implemented
  • Deprecated - Decision is no longer valid
  • Superseded - Decision replaced by another decision

Status Transitions:

Proposed → Accepted (after approval)
Accepted → Deprecated (when no longer valid)
Accepted → Superseded (when replaced)

Updating Decisions

When to Update:

  • Decision changes - Decision evolves or changes
  • New information - New context or constraints discovered
  • Superseded - Decision replaced by new decision

How to Update:

  1. Create new version - Create new ADR/BDR with updated decision
  2. Link to old - Link new decision to old decision
  3. Update status - Mark old decision as "Superseded"
  4. Document changes - Document what changed and why

Examples

Example ADR

ADR-0001: Use Cosmos DB for Event Storage

# ADR-0001: Use Cosmos DB for Event Storage

## Status
Accepted

## Context
We need to store events for the Audit Platform. Events are append-only,
high-volume, and need to be queryable by tenant, time range, and event type.

## Decision
Use Azure Cosmos DB (SQL API) for event storage.

## Consequences
**Positive:**
- Scalable to millions of events
- Multi-tenant support built-in
- Queryable by multiple dimensions
- Global distribution support

**Negative:**
- Cost increases with volume
- Learning curve for team
- Vendor lock-in to Azure

## Alternatives Considered
- **Azure Blob Storage** - Cheaper but not queryable
- **SQL Server** - Familiar but doesn't scale as well
- **Event Hubs** - Good for ingestion but not for querying

## Notes
- Consider partitioning strategy for cost optimization
- Monitor RU consumption

Example BDR

BDR-0001: Generated Code Ownership

# BDR-0001: Generated Code Ownership

## Status
Accepted

## Context
We need to clarify IP ownership for Factory-generated code to build customer
trust and enable contract negotiations.

## Decision
Customers own all code generated into their Azure DevOps repositories.
ConnectSoft retains IP in Factory runtime and templates.

## Rationale
- Builds customer trust (no vendor lock-in)
- Competitive advantage vs low-code platforms
- Aligns with customer expectations
- Enables clear contract language

## Business Impact
- Differentiates from competitors
- Enables enterprise sales
- Reduces customer concerns about IP

## Alternatives Considered
- **ConnectSoft owns generated code** - Would create vendor lock-in
- **Shared ownership** - Too complex, legal issues
- **Open source generated code** - Not appropriate for customer IP

## Notes
- See [Code Ownership Model](../business-model/code-ownership-model.md)
- Legal team reviewed and approved