Architecture Decision Records¶

This section contains Architecture Decision Records (ADRs) for the nj_legislature project. ADRs document significant architectural decisions made during the development of this project, including the context, decision, and consequences.

What is an ADR?¶

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

• Understand the reasoning behind past decisions
• Avoid revisiting settled discussions
• Onboard new team members more effectively
• Track the evolution of the architecture over time

Format¶

Each ADR follows a consistent structure:

• Title: Brief description of the decision
• Status: Proposed, Accepted, Deprecated, or Superseded
• Context: The issue motivating this decision
• Decision: The change being proposed or has been agreed upon
• Consequences: The resulting context after applying the decision

Records¶

• ADR-01: Workspace Structure - Decision to use a monorepo workspace structure with uv
• ADR-02: Branch Naming Convention - Standardized branch naming pattern for development

Creating New ADRs¶

When making significant architectural decisions:

1. Create a new file: docs/adr/NN-title-with-dashes.md (where NN is the next number)
2. Follow the standard ADR template
3. Update this index with a link to the new ADR
4. Submit for team review

Resources¶

• ADR GitHub Organization - Collection of ADR resources and tools
• Documenting Architecture Decisions - Original blog post by Michael Nygard