Skip to content

Architecture Decision Records (ADRs)

This directory contains Architecture Decision Records (ADRs) documenting significant architectural and design decisions made in the Portfolio Management System.

What is an ADR?

An Architecture Decision Record captures an important architectural decision along with its context and consequences. ADRs help:

  • Preserve institutional knowledge - Future developers understand why decisions were made
  • Enable informed evolution - Changes can be evaluated against original constraints
  • Facilitate onboarding - New team members can quickly understand architectural choices
  • Document trade-offs - Record both benefits and costs of each decision

ADR Format

Each ADR follows a consistent structure (see TEMPLATE.md):

  1. Title - Short noun phrase describing the decision
  2. Status - Proposed, Accepted, Deprecated, or Superseded
  3. Context - Problem being solved and constraints
  4. Decision - What was decided (specific and actionable)
  5. Consequences - Positive, negative, and neutral impacts
  6. Alternatives - Options considered and why they were rejected
  7. References - Links to issues, discussions, external resources

ADR Index

ADR Title Status Date
001 Ruff-Only Golden Path Accepted 2025-11-07
002 Modular Monolith Architecture Accepted 2025-11-07
003 Statistics Caching Pattern Accepted 2025-11-07
004 Incremental Resume Pattern Accepted 2025-11-07

Creating a New ADR

  1. Copy the template:
cp docs/architecture/decisions/TEMPLATE.md docs/architecture/decisions/ADR-NNN-short-title.md

  1. Choose the next ADR number - Increment from the last ADR (use leading zeros: 001, 002, etc.)

  2. Fill in all sections - Be specific about context, decision, and consequences

  3. Submit for review - ADRs should be reviewed like code (via PR)

  4. Update this README - Add your ADR to the index table above

ADR Lifecycle

  • Proposed - Initial draft, under discussion
  • Accepted - Approved and implemented
  • Deprecated - No longer recommended but not superseded
  • Superseded - Replaced by a newer ADR (reference the replacement)

Guidelines

Good ADRs are:

  • ✅ Concise - Focus on the decision, not implementation details
  • ✅ Specific - Include concrete examples and constraints
  • ✅ Timely - Written close to when the decision was made
  • ✅ Honest - Document trade-offs, not just benefits

Avoid:

  • ❌ Documenting trivial decisions (use code comments instead)
  • ❌ Vague language ("better", "faster" without metrics)
  • ❌ Omitting alternatives (show you considered options)
  • ❌ Changing ADRs after acceptance (create new ADR superseding old one)

References