Understanding Mailwoman

This track is for readers who want to understand why Mailwoman exists, what problem it solves, what it parsesaddress parsingThe process of decomposing a free-text postal address string into structured components — house number, street name, locality, region, postcode, and country — so a geocoder can resolve them to coordinates., and how it works — in that order. The articles are grouped into five sections that match the sidebar, and build on each other within each section — but each article is self-contained enough to be read independently.

The five sections

The Problem (articles 1–7)

The fundamentals of postal addressing — the things a parser parsesaddress parsingThe process of decomposing a free-text postal address string into structured components — house number, street name, locality, region, postcode, and country — so a geocoder can resolve them to coordinates. and a resolverresolverThe component that converts parsed address components (locality, region, postcode) into coordinates by looking them up in the gazetteer. The resolver ranks candidates by name match, population, and proximity, and returns the best-matching place with its centroid or polygon. resolves.

1. What is an address? — the data modelneural classifierThe machine learning model at the core of Mailwoman's parser — a transformer encoder (~30M parameters) trained from scratch to do BIO token classification over addresses. It learns the 'grammar' of address formats; the gazetteer supplies the 'atlas.', moved from concepts.
2. How mail delivery actually works — the postal system is already fuzzy. It tolerates ambiguity through human intervention.
3. What is a postcode? — postcodespostcodeThe country-specific postal code (US ZIP, French code postal, etc.). Mailwoman handles postcode parsing entirely by rule classifier — a regex problem, not an ML one. are routing instructions, not geographic areas. International comparison.
4. What is a ZIP Code and how is it structured? — the US 11-digit system in detail. Why US-trained parsers fail on non-US postcodespostcodeThe country-specific postal code (US ZIP, French code postal, etc.). Mailwoman handles postcode parsing entirely by rule classifier — a regex problem, not an ML one..
5. How can a building have two addresses? — mailing vs 911 vs utility vs management. An address is a protocol, not a property.
6. What is an intersection address? — crossing streetsstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels. as locations. Why not all addresses have building numbers.
7. What is a concordance? — how the resolverresolverThe component that converts parsed address components (locality, region, postcode) into coordinates by looking them up in the gazetteer. The resolver ranks candidates by name match, population, and proximity, and returns the best-matching place with its centroid or polygon. validates that parsed components form a coherent real-world place.

Why It's Hard (articles 8–20)

Why the domain resists rules. If you are sceptical that address parsingaddress parsingThe process of decomposing a free-text postal address string into structured components — house number, street name, locality, region, postcode, and country — so a geocoder can resolve them to coordinates. needs a neural modelneural classifierThe machine learning model at the core of Mailwoman's parser — a transformer encoder (~30M parameters) trained from scratch to do BIO token classification over addresses. It learns the 'grammar' of address formats; the gazetteer supplies the 'atlas.', start here.

8. Addresses that break geocoders — concrete failure examples, moved from concepts.
9. How humans break addresses — the failure taxonomy. Real input is messier than any database expects.
10. The database fallacy — why "just store all addresses" is economically infeasible and geometrically wrong.
11. The 90% trap — why 90% geocoder coveragecoverageThe fraction of a population or region for which a data source has real, non-placeholder entries — e.g. 47% rooftop coverage on Texas addresses. Distinct from accuracy on the rows that are present. is deceptively expensive.
12. The tokenization tautology — why traditional rule-based parsers hit a structural ceiling.

Falsehoods about addresses

Inspired by and citing Michael Tandy's original catalogue. Each article takes one category of falsehood, explains how traditional geocoders handled it, and what Mailwoman's neural approach changes.

13. Overview — the taxonomy and why it matters for Mailwoman.
14. Address format — non-ASCII, variable ordering, special characters, changing addresses.
15. Street names — missing suffixes, numbered streetsstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels., recurring names, no streetsstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels. at all.
16. Numbers in addresses — zero, negative, fractions, duplicates, ranges.
17. Postcodes — leading zeros, multi-citylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighbourhood in the hierarchy., per-building, missing postcodespostcodeThe country-specific postal code (US ZIP, French code postal, etc.). Mailwoman handles postcode parsing entirely by rule classifier — a regex problem, not an ML one..
18. Administrative hierarchy — no statesregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality., no counties, duplicate cities, city-statesdual-role placeA place that is two placetypes at once — Berlin as both a city and a state, Washington DC as city and district. Resolved using the coincident-roles relation plus hierarchy completion..
19. Shapes and dimensions — not a point, not a polygon, not a building, not at ground level, not unique per coordinate.
20. Precision and frontages — not one correct coordinate, not always "close enough," not necessarily the front door.

Alternatives (articles 21–30)

Steel-manning the reasonably defensible compromises that work for most applications, before making the case for Google's API and geocode.earth.

21. The case for simple geocoders — when simple is the right choice, and when it isn't.

The simple architectures

22. Postcode-only — extract the postcodepostcodeThe country-specific postal code (US ZIP, French code postal, etc.). Mailwoman handles postcode parsing entirely by rule classifier — a regex problem, not an ML one., centroid the result.

23. Locality-only — find the citylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighbourhood in the hierarchy., centroid it.

24. Gazetteer-first — skip parsingaddress parsingThe process of decomposing a free-text postal address string into structured components — house number, street name, locality, region, postcode, and country — so a geocoder can resolve them to coordinates., treat as information retrieval.

25. Normalize to match — strip, lowercase, fuzzy-match against a known database.

26. Regex-anchored fields — extract the 3-4 fields you care about, ignore the rest.

27. Close-enough — define your precisionprecisionOf the spans the model labeled as a given tag, the fraction it got right. High precision means few false positives. Paired with recall to compute F1. requirement, pick the cheapest approach, stop.

28. Human-in-the-loop — don't parseaddress parsingThe process of decomposing a free-text postal address string into structured components — house number, street name, locality, region, postcode, and country — so a geocoder can resolve them to coordinates., suggest, let the user confirm.

29. Why not just use Google's API? — pricing, terms, lock-in, and when renting is the right choice.

30. Why not use geocode.earth? — the open-source hosted alternative and its PeliasPeliasAn open-source geocoder, Mailwoman's spiritual predecessor. parser ceiling.

Our Approach (articles 31–38)

Mailwoman's design, and how it got here.

31. Why a neural parser? — the bitter-lesson argument applied to address parsingaddress parsingThe process of decomposing a free-text postal address string into structured components — house number, street name, locality, region, postcode, and country — so a geocoder can resolve them to coordinates.. Opens the case for everything that follows.
32. The knowledge ladder — the decomposition principle behind the staged pipelinestaged pipelineMailwoman's runtime architecture: a sequence of pure-function stages (normalize → query-shape → locale-gate → kind-classifier → phrase-grouper → classifier → decoder) connected by typed handoffs. Each stage is published as its own npm package..
33. How it works now — the current rule + neural hybrid.
34. The staged pipeline — the Mailwoman runtime end-to-end.
35. From Pelias to Mailwoman — the short historical bridge.
36. What the eval numbers mean — the golden-set results, and how to read each pipelinestaged pipelineMailwoman's runtime architecture: a sequence of pure-function stages (normalize → query-shape → locale-gate → kind-classifier → phrase-grouper → classifier → decoder) connected by typed handoffs. Each stage is published as its own npm package. mode's metrics.
37. How it used to work — Mailwoman v1 (rule-based) in detail.
38. How it will work — the near-future roadmap.

Exotic point-of-interest queries (articles 39–44)

Not every geocoder query is an address. A large fraction of real-world searches ask for points of interest — named placesvenueA named, non-address place — a business, building, park, or stadium. Mailwoman's free-text point-of-interest component, added as a Tier 2 fine label., categories, brands, landmarks, and transit infrastructure.

39. Overview — what counts as a POIpoint of interest (POI). A named place that is not strictly an address — landmark, transit stop, venue, amenity, or franchise. Mailwoman tags these as venue and resolves them through the gazetteer. query vs an address query.
40. Amenity queries — water fountain, gas station, ATM, pharmacy.
41. Franchise and brand queries — Walmart, McDonalds, Hilton, Starbucks.
42. Regional variants — servo, bodega, マクド, off-licence, chemist.
43. Landmark queries — Eiffel Tower, Golden Gate Bridge, Empire State Building.
44. Transit queries — subway station, bus stop, airport, train station.

Reference

Glossary — every technical term defined on first use.

Reading order

If you are sceptical about the whole project, read The Problem and the first five entries of Why It's Hard in order (articles 1–12), then jump to Why a neural parser? (article 31). That's the domain case, the failure case, and the pitch, in under an hour. If you are still sceptical after that, the project has failed to make its case — open an issue.

If you are new to geocodinggeocodingThe process of converting an address into geographic coordinates (latitude and longitude). Mailwoman geocodes in a multi-tier cascade: exact address-point match → street interpolation → locality centroid. Each tier is progressively coarser but more widely available. but curious, start with The Problem (articles 1–7) in order. It grounds the domain vocabularyvocabularyThe fixed set of tokens a tokenizer can produce. Mailwoman's SentencePiece vocabulary is tens of thousands of subword pieces, with byte fallback for anything outside it. everything after it assumes.

If you are from the PeliasPeliasAn open-source geocoder, Mailwoman's spiritual predecessor. world, read From Pelias to Mailwoman (article 35), then How it works now (article 33). Those two articles bridge your existing knowledge to the current system.

If you want to go deeper, see the concepts/ track — per-topic deep dives into tokenization, BIO labelsBIO tagging (Begin-Inside-Outside). A token-level labeling scheme where each token is tagged as B-X (beginning of an entity of type X), I-X (inside an entity of type X), or O (outside any entity). Mailwoman uses BIO over SentencePiece tokens to annotate address components., the CRFCRF (Conditional Random Field). A statistical modeling method that predicts structured outputs by modeling dependencies between adjacent labels. Mailwoman uses a linear-chain CRF as the Viterbi decoder at inference time to enforce BIO label consistency — a B-street must be followed by I-street or O, never I-locality. decoderdecoderIn a transformer encoder-decoder model, the part that produces output sequences. Mailwoman's classifier is encoder-only (no decoder); the 'CRF decoder' is a different thing — a structured-prediction layer that picks the best label sequence from the encoder's outputs., ONNX runtimeONNX (Open Neural Network Exchange). An open format for machine learning models that enables interoperability between training frameworks and inference runtimes. Mailwoman ships its trained model as an ONNX file so it can run in Node.js and the browser via onnxruntime., trainingtrainingThe process of adjusting a model's parameters so its predictions match labeled examples, by repeatedly measuring error and nudging the weights to reduce it. Distinct from inference, when the trained model is run on new input. pipelinestaged pipelineMailwoman's runtime architecture: a sequence of pure-function stages (normalize → query-shape → locale-gate → kind-classifier → phrase-grouper → classifier → decoder) connected by typed handoffs. Each stage is published as its own npm package., corpuscorpusThe BIO-labeled training data used to train Mailwoman's neural classifier. Assembled from real sources (OpenAddresses, National Address Database) and synthetic shards (boundary stress, order variants, negative space). Managed by @mailwoman/corpus. construction, and more.

A note on language

The team behind Mailwoman speaks many languages, and English is a second language for many readers. Our goal in these docs is plain English with technical terms defined on first use. If a sentence is hard to follow, that is a documentation bug — please open an issue.

Where this lives in the repo

docs/
├── articles/
│   ├── understanding/     ← you are here
│   ├── concepts/          ← per-concept deep dives
│   ├── plan/              ← operator + agent technical plan
│   └── evals/             ← per-version evaluation reports
└── src/pages/demo/        ← the live browser-side demo