Skip to content
  • decisions
  • adr
  • bdr
  • process

Decisions – Overview and Process

This document defines ConnectSoft's decision system: why we use ADRs (Architecture Decision Records) and BDRs (Business Decision Records), when to write each type, numbering conventions, status lifecycle, and how decisions connect to architecture, roadmaps, governance, and business models. It is written for architects, product managers, Dmitry, future team members, and partners with access.

The decision system ensures critical choices are visible, searchable, and provide context for future contributors. This page explains how to use and extend the existing ADR/BDR series.

Important

Decision Requirement: Any decision that significantly affects architecture, products, pricing, branding, or governance MUST have an ADR or BDR. This ensures decisions are visible, searchable, and provide context for future contributors.

Why We Use ADRs and BDRs

Key Benefits:

  • Keep Critical Decisions Visible - Decisions are documented, searchable, and accessible to all stakeholders
  • Avoid Repeating Discussions - Historical context prevents rehashing the same debates
  • Provide Context for Future Contributors - New team members and partners understand why choices were made
  • Link Decisions to Implementation - Connect decisions to code, architecture, strategy, and roadmaps
  • Track Evolution - See how decisions evolved over time through supersession chains

See: How to Write a Good ADR for ADR writing guide.

See: How to Write a Good BDR for BDR writing guide.

Types of Decisions

Type Scope Examples
Architecture Decision (ADR) Technical architecture & implementation Event bus choice, tenancy model, observability stack, ORM selection
Business Decision (BDR) Strategy, pricing, domains, product models Marketplace tiers, domain usage strategy, pricing models, partner policies
Minor Operational Choice Day-to-day tweaks Naming in one service, temporary workaround (no ADR/BDR needed)

Note

Not Every Decision Needs an ADR/BDR: Small, day-to-day operational choices don't need formal records. ADRs and BDRs are for non-trivial, long-lived choices that affect architecture, products, pricing, branding, or governance.

Choosing ADR vs BDR

Guidelines:

  • ADR = Architecture/Tech Design - Code, infrastructure, patterns, technical choices
  • BDR = Business/Strategy - Pricing, domains, product models, partner policies, marketplace rules

Decision Table:

Scenario Use ADR or BDR? Notes
Pick primary event bus technology ADR Technical choice, long-term impact on all services
Define code-ownership model for templates BDR (with ref to ADR if tech implications) Business policy with tech implications
Decide marketplace revenue share model BDR Business & partner-focused decision
Choose where connectsoft.io vs .ai is used BDR Goes with domains/branding strategy
Select standard observability stack ADR Technical choice for all services
Define Factory pricing tiers BDR Business model and pricing decision
Choose ORM framework (NHibernate) ADR Technical architecture choice
Partner program structure and benefits BDR Business and partner strategy

Tip

If in Doubt: Start with BDR if it's mostly business-facing, or ADR if mostly technical. You can always link between them if a decision has both technical and business aspects.

Numbering, File Naming, and Status

Numbering Convention

  • ADRs: ADR-0001, ADR-0002, ADR-0003, ...
  • BDRs: BDR-0001, BDR-0002, BDR-0003, ...

Rules: - Sequential numbering (no gaps) - Each decision gets a unique number - Numbers are permanent (don't renumber)

File Naming

ADR Files: - Path: docs/decisions/adr/ADR-XXXX-title-slug.md - Example: docs/decisions/adr/ADR-0001-use-log4brains-for-architecture-decision-records.md

BDR Files: - Path: docs/decisions/bdr/BDR-XXXX-title-slug.md - Example: docs/decisions/bdr/BDR-0001-generated-code-ownership.md

Naming Rules: - Use lowercase with hyphens for slug - Keep title descriptive but concise - Match the title in the document header

Status Definitions

Status Meaning Usage
Proposed Under discussion, not yet final Initial draft, open for review
Accepted Officially in effect Decision is active and should be followed
Superseded Replaced by another ADR/BDR Link to the new decision
Rejected Considered but explicitly not chosen Rare, but useful to document why not

Important

Status Requirement: Every ADR/BDR MUST have a status. Superseded records must link to the new decision, and the new decision must reference what it supersedes. This maintains a clear decision history.

See: ADR Index for current ADR statuses.

See: BDR Index for current BDR statuses.

Decision Lifecycle and Workflow

Lifecycle Stages

  1. Identify Decision - Recognize that a significant choice needs documentation
  2. Draft ADR/BDR - Write the decision record using the template
  3. Review - Get feedback from Dmitry, owners, and relevant stakeholders
  4. Accept/Reject - Final decision is made, status updated
  5. Implement - Decision is implemented in code, strategy, or processes
  6. Optionally Supersede - If decision changes, create new ADR/BDR and mark old as Superseded

Workflow Steps

For New Decisions:

  1. Determine Type - ADR (technical) or BDR (business)?
  2. Get Next Number - Check existing ADRs/BDRs, use next sequential number
  3. Create File - Use template, follow naming convention
  4. Write Decision - Context, decision, rationale, consequences, alternatives
  5. Set Status - Start as "Proposed"
  6. Review - Share with stakeholders, get feedback
  7. Update Status - Change to "Accepted" when finalized
  8. Link - Add links to/from related docs (architecture, strategy, roadmaps)

For Superseding Decisions:

  1. Create New ADR/BDR - Document the new decision
  2. Link Old Decision - Reference what it supersedes
  3. Update Old Decision - Change status to "Superseded", link to new decision
  4. Update Indexes - Ensure both decisions are properly indexed

See: How to Write a Good ADR for detailed ADR workflow.

See: How to Write a Good BDR for detailed BDR workflow.

Linking Decisions to Other Docs

ADR Linking

ADRs Should Link To: - Relevant architecture docs (Clean Architecture, Event-Driven, Cloud-Native) - Templates and libraries documentation - Code references (repos, specific implementations) - Related ADRs (if decision builds on or conflicts with others)

Example Links: - From ADR: "See Clean Architecture & DDD for architectural principles." - From ADR: "This decision aligns with ADR-0001 on documentation tooling."

BDR Linking

BDRs Should Link To: - Strategy docs (Business Strategy, GTM Strategy, Marketplace Strategy) - Roadmaps (2026 Roadmap, Factory Roadmap, Platforms Roadmap) - Governance docs (IP, SLAs, Security, Data Residency) - Business model docs (Factory Business Model, Squads Business Model, Platforms Business Model) - Related BDRs (if decision builds on or conflicts with others)

Example Links: - From BDR: "See Business Strategy for overall business objectives." - From BDR: "This decision is reflected in 2026 Roadmap." - From BDR: "Related to BDR-0001 on code ownership."

Reverse Linking

Major Docs Should Link Back:

  • Architecture docs should list relevant ADRs
  • Strategy docs should list relevant BDRs
  • Roadmaps should reference decisions that inform milestones
  • Governance docs should link to BDRs that define policies

Example Structure in Docs:

## Related Decisions

- [ADR-0001](../adr/adr-0001-use-log4brains-for-architecture-decision-records.md) - Use log4brains for Architecture Decision Records

## Related Documents

- [Factory Overview](../factory/overview.md) - Factory architecture
- [Event-Driven Mindset](../architecture/event-driven-mindset.md) - Event patterns

Decision

Decision Documentation Practice: All major strategy/architecture docs should list their key ADR/BDR references. This creates bidirectional links between decisions and implementation, making it easy to understand why choices were made and how they connect to broader strategy.