Understanding Mailwoman

This track is for readers who want to understand why Mailwoman exists, what problem it solves, what it parses, and how it works — in that order. The articles build on each other, but each is self-contained enough to be read independently.

The four layers

Tier 0 — The problem (articles 2–7)

These six articles establish the domain. If you are sceptical that address parsing needs a neural model, start here.

1. How mail delivery actually works — the postal system is already fuzzy. It tolerates ambiguity through human intervention.
2. How humans break addresses — the failure taxonomy. Real input is messier than any database expects.
3. The database fallacy — why "just store all addresses" is economically infeasible and geometrically wrong.
4. The tokenization tautology — why traditional rule-based parsers hit a structural ceiling.
5. The 90% trap — why 90% geocoder coverage is deceptively expensive.
6. Why a neural parser? — the bitter-lesson argument applied to address parsing. Bridges Tier 0 → Tier 1.

Tier 0.5 — Postal address concepts (articles 8–12)

These five articles explain the fundamental concepts of postal addressing — the things a parser actually parses and a resolver actually resolves. New as of May 2026.

7. What is a postcode? — postcodes are routing instructions, not geographic areas. International comparison.
8. 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 postcodes.
9. What is a concordance? — how the resolver validates that parsed components form a coherent real-world place.
10. What is an intersection address? — crossing streets as locations. Why not all addresses have building numbers.
11. How can a building have two addresses? — mailing vs 911 vs utility vs management. An address is a protocol, not a property.

Tier 1 — The architecture (articles 13–20)

These describe Mailwoman's design. Most existed before May 2026 and have been reordered to follow the domain articles.

12. What is an address? — the data model, moved from concepts.
13. Addresses that break geocoders — concrete failure examples, moved from concepts.
14. From Pelias to Mailwoman — the short historical bridge.
15. How it used to work — Mailwoman v1 (rule-based) in detail.
16. How it works now — the current rule + neural hybrid.
17. How it will work — the near-future roadmap.
18. The knowledge ladder — the decomposition principle behind the staged pipeline.
19. The staged pipeline — the Mailwoman runtime end-to-end.

Reference

20. Glossary — every technical term defined on first use.

Appendix

21. Why not just use Google's API? — pricing, terms, lock-in, and when renting is the right choice.
22. Why not use geocode.earth? — the open-source hosted alternative and its Pelias parser ceiling.

The case for simple geocoders

Steel-manning the reasonably defensible compromises that work for most applications.

23. Overview — when simple is the right choice, and when it isn't.
24. Normalize to match — strip, lowercase, fuzzy-match against a known database.
25. Postcode-only — extract the postcode, centroid the result.
26. Gazetteer-first — skip parsing, treat as information retrieval.
27. Regex-anchored fields — extract the 3-4 fields you care about, ignore the rest.
28. Locality-only — find the city, centroid it.
29. Human-in-the-loop — don't parse, suggest, let the user confirm.
30. Close-enough — define your precision requirement, pick the cheapest approach, stop.

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.

31. Overview — the taxonomy and why it matters for Mailwoman.
32. Numbers in addresses — zero, negative, fractions, duplicates, ranges.
33. Street names — missing suffixes, numbered streets, recurring names, no streets at all.
34. Postcodes — leading zeros, multi-city, per-building, missing postcodes.
35. Administrative hierarchy — no states, no counties, duplicate cities, city-states.
36. Address format — non-ASCII, variable ordering, special characters, changing addresses.
37. Shapes and dimensions — not a point, not a polygon, not a building, not at ground level, not unique per coordinate.
38. Precision and frontages — not one correct coordinate, not always "close enough," not necessarily the front door.

Exotic point-of-interest queries

Not every geocoder query is an address. A large fraction of real-world searches ask for points of interest — named places, categories, brands, landmarks, and transit infrastructure.

39. Overview — what counts as a POI 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.

Reading order

If you are sceptical about the whole project, read Tier 0 in order (articles 2–6). It should take about 45 minutes. If you are still sceptical after that, the project has failed to make its case — open an issue.

If you are new to geocoding but curious, start with What is an address? (article 13), then read Tier 0. The data-model article grounds the domain arguments.

If you are from the Pelias world, read From Pelias to Mailwoman (article 14), then How it works now (article 16). 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 labels, the CRF decoder, ONNX runtime, training pipeline, 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