Addresses - Design decisions

What is an ADR?

We use the ADR (Architecture Decision Record) to structure design decision documentation. Each ADR covers three things: the context that prompted the decision, the decision itself, and its consequences — including trade-offs and any open questions.

ADR 001 - Suggested address confirmation

• Decision date: August 17, 2026

Context

USPS can validate a submitted address but suggest different formatting or unit information than what the user originally entered.

Decision

Show the user a confirmation screen after submission so they can choose whether to save their original entry or the USPS-suggested address.

Consequences

Positive:

• Improves delivery accuracy by giving users the chance to accept USPS-standardized formatting.

Negative / watch items:

• Adds an extra screen/step for users whose address needs a suggested correction.

ADR 002 - Undeliverable address warning

• Decision date: August 17, 2026

Context

Mail sent to a previously validated address can still be returned to sender later, for example if the person no longer lives there.

Decision

Flag the address and show a warning alert the next time the user visits a form that uses that address, letting them confirm or update it.

Consequences

Positive:

• Surfaces undeliverable addresses proactively instead of letting mail continue to fail silently.

Negative / watch items:

• Requires a background process to detect returned mail and flag the address accordingly.

ADR 003 - Address mismatch on in-progress forms

• Decision date: August 17, 2026

Context

If a user updates their address in their VA.gov profile while they have an in-progress form, application, or claim, the address already saved on that form doesn’t automatically update to match.

Decision

Show an info alert when the user returns to review the form, comparing the address saved on the form to the address on their profile, so they can confirm which one is correct before submitting.

Consequences

Positive:

• Prevents users from unknowingly submitting a form with an outdated address.

Negative / watch items:

• Requires reliably pulling and comparing both the form address and profile address at review time.

ADR 004 - Address updates apply everywhere

• Decision date: August 17, 2026

Context

Users may not realize that changing their address in one place, such as their VA.gov profile, updates that address across all their VA accounts and records.

Decision

Show an informational message clarifying that an address update will apply everywhere, not just to the current form or page.

Consequences

Positive:

• Sets accurate expectations up front and reduces confusion or support cases from users surprised by the change.

Negative / watch items:

• None significant.