Country-Aware Address Form

This project is a country-aware address form that dynamically restructures itself based on the country a user selects. Different countries have fundamentally different address formats — the United States uses a city, state, and ZIP code; the United Kingdom uses a town, county, and postcode; Japan reverses the entire hierarchy. A single static form fails all of them. This form adapts.

What makes it interesting is the validation approach. Once a user fills out an address, they can verify it via Claude AI, which interprets the address in plain language and flags issues that structured validation often misses — ambiguous apartment numbers, likely typos in street names, or combinations of fields that look technically valid but wouldn’t reach a real recipient.

Claude excels at reasoning about edge cases, explaining what might be wrong in terms a person can act on, and handling address formats from countries where postal databases have sparser coverage. Rather than returning a binary pass/fail, it returns a plain-English explanation alongside a corrected version of the address — something a person can actually use.

The underlying challenge this solves is real: international address collection is one of those problems that looks simple until you try to build it properly. Most implementations either force every country into a US-shaped form and lose data, or ship a massive static configuration file per country. This project explores what it looks like when you bring an LLM into the loop — not as a fallback, but as the primary validation layer.

The form operates in two stages. In the first stage, selecting a country triggers a field-swap: a per-country configuration determines which fields appear, what they're labeled, in what order they render, and what input constraints apply (e.g. postal code format). In the second stage, submitting the form sends the collected address to Claude for validation.

Why Claude? Claude handles the cases rule-based validation misses: rare address formats, ambiguous inputs, and natural-language explanations of what’s wrong and how to fix it. Rather than returning a binary pass/fail, it returns a corrected version alongside a plain-English explanation — something a person can actually act on.

Built and written from the perspective of a Product Manager learning to work hands-on with APIs and AI tooling.

• 1

  Address formats are far more varied than they look Before building this, I assumed address differences between countries were cosmetic — a different field order, maybe a different name for "zip code." In practice, the differences run deeper: some countries don't use states at all, some put the postal code before the city, and some have address lines that carry meaning encoded in their position. A form that ignores these conventions doesn't just look wrong — it loses real data.

• 2

  LLMs are better validators than they look on paper I expected Claude to be useful for edge cases but assumed rule-based validation would be the backbone. In practice, Claude handled not just unusual formats but also explained the issues in terms a person could act on — which turned out to be more valuable than a binary pass/fail. The shift from thinking about validation as a lookup problem to thinking about it as a reasoning problem changed how I approached the prompt design.

• 3

  Dynamic form state is harder to manage than it looks Re-rendering the form on country change means deciding what to preserve and what to discard. Keeping values that no longer map to valid fields creates silent data loss. Clearing everything frustrates users who switched countries by accident. Getting the state transitions right — and communicating them clearly to the user — turned out to be as interesting a design problem as the validation logic.

• 4

  Prompt design for structured output matters as much as schema design Getting Claude to return validation feedback in a consistent, actionable format required careful prompt engineering — specifically, constraining the output structure so the UI could parse and display it predictably. Vague prompts produced helpful prose that was hard to render cleanly. Adding explicit output constraints (field-level vs. form-level feedback, severity levels) made the responses both more useful and more reliable.

Built without frameworks or build tools — vanilla JavaScript, Claude AI, and a single HTML file.