Skip to content

Record Architecture Decisions

Context and Problem Statement

Famlab is a complex system that will require many architectural decisions over its development lifecycle. We need a systematic way to:

  • Document important decisions and their rationale
  • Track the evolution of our thinking
  • Provide context for future contributors
  • Enable informed decision-making by understanding past choices

Decision Drivers

  • Transparency: Decisions should be visible and understandable to all contributors
  • Accountability: Clear ownership and rationale for architectural choices
  • Evolution: Ability to revisit and change decisions as understanding improves
  • Onboarding: New contributors need context on why systems are designed as they are
  • Consistency: Standardized format for capturing decisions

Considered Options

  • No formal process: Document decisions ad-hoc in code comments or commit messages
  • Wiki-based documentation: Use a wiki system to capture decisions
  • Architecture Decision Records (ADRs): Formal ADR process with structured templates
  • External tools: Use dedicated decision-tracking tools

Decision Outcome

Chosen option: Architecture Decision Records (ADRs) using the MADR (Markdown Architectural Decision Records) template format.

Consequences

  • Good, because ADRs live in the same repository as code (version controlled)
  • Good, because MADR provides clear, consistent structure
  • Good, because markdown format is easy to read, write, and review
  • Good, because it's a lightweight process with minimal overhead while providing maximum value
  • Good, because it's an industry standard with well-established patterns and tooling support
  • Bad, because it requires discipline to document decisions consistently
  • Bad, because template compliance needs to be maintained for consistency

Pros and Cons of the Options

No formal process

  • Good, because zero process overhead
  • Bad, because decisions lost in history, difficult to understand rationale
  • Bad, because inconsistent documentation quality

Wiki-based documentation

  • Good, because easy to write and update
  • Bad, because separate from code, can become stale
  • Bad, because no version control of decision history

Architecture Decision Records (ADRs)

  • Good, because version controlled alongside code
  • Good, because structured, searchable format
  • Good, because industry best practice
  • Bad, because requires consistent process discipline

External tools

  • Good, because dedicated features for decision tracking
  • Bad, because additional tool overhead
  • Bad, because separation from code repository

More Information