Places and names
How Clara works out which property a caller means, when people use the property name, the legal entity, the street, a nearby street or a building nickname interchangeably.
Verdict. One standard way to handle every name a place goes by, not a one-off fix per client and not a new entity layer. Each name is a small record with a kind and the place(s) it points to. Clara looks names up through the search tool she already has, which either finds one place, asks a smart follow-up, or hands off. It keeps the team's decision (aliases plus prompts, no new entity class), uses names that fit the code we already have, and builds on the existing listings and nearby-streets work, so a client's unusual setup becomes data to enter, not code to rewrite.
Status (2026-10-01): storing names (#13966), the matcher and its follow-up question (#14044, #14114), the strict mode email uses (#14661) and the whole-word fix (#14608) are live. In review: the name editor (#14193), Clara's search (#14677), guest-card emails (#14676), and the spreadsheet and map-street loaders (#14667, #14685).
How it connects
Property system
Legal entities and owners (the LLC a resident pays rent to).
Map data
The street each address is on, plus nearby and cross streets. Reuses the listings geo work, lifted to the property.
Onboarding and the admin page
The client fills an onboarding spreadsheet that a script loads (run by us). After that, people add, edit and remove a property's also-known-as names themselves on its admin page.
Missed calls
Phrases Clara couldn't match become suggested names. Never used until a person confirms them in that editor.
PropertyAlias records, per company
Text · kind · target(s) · source · status. Kinds: official, everyday, legal entity, street, nearby street, master tenant, region. A target is a whole property or a set of units in it (one building). One name may point at several places, and that's how "an entity with two properties" works.
Caller
"I'm calling about Holdings 22."
Clara
Handles the conversation only.
search_properties tool
The tool Clara already has. Its insides are replaced; no new tool.
resolvePropertyByName
Tested code, and the one function behind today's resolveProperty: normalize, exact, close, then house number + street. Uses caller context first. Properties we don't handle are invisible to it.
One match
Confirm it back ("the one on Willow, right?"), then book the tour or open the work order.
Several matches
pickDistinguishingName chooses what tells them apart: "Is that the one on Pine or the one on Elm?"
No match
Hand off honestly, and record the phrase as a suggested name for review.
The pieces
| Piece | Name | What it is |
|---|---|---|
| A name for a place | PropertyAlias | One record per name, stored in the company's own partition under PROPALIAS#<name>#<id>. Needs no new database index. |
| Its kind | PropertyAliasKind | official · everyday · legalEntity · street · nearbyStreet · masterTenant · region |
| What it points to | PropertyAliasTarget | A property, or a set of units inside one (a building or a master-tenant block). |
| Where it came from | source | pms · geo · audit · learned · manual (typed in on the admin page). Status: active · suggested · retired. |
| The matcher | resolvePropertyByName | Deterministic and unit-tested; the one function behind today's resolveProperty. Returns the existing one / several / none result, plus a "matched by" label saying which name did the matching. |
| The follow-up | pickDistinguishingName | Picks the detail that splits the candidates, usually street, building or bedroom count. |
| Clara's door | search_properties | Clara's existing tool, with its insides replaced. The prompt never carries the whole name list, so it scales to thousands of properties. |
| The name editor | property admin page | Where people add, edit and remove a property's also-known-as names themselves, and confirm suggested ones. The onboarding spreadsheet stays for loading many at once. |
| Properties we don't handle | the In Propflow switch | The per-building on/off switch that already exists on the company's Buildings page (absent means on), not a new field. "If we don't handle it, Clara shouldn't know about it." A building switched off is never matched, never listed, never named, and kept off dashboards. |
| No switch | on for everyone | There is no on/off setting for names (Gera, 2026-10-01: "there shouldn't be a switch entirely, it should just be on by default"). A company with no names entered still resolves on official name and address through the same matcher. |
Messy setups it has to absorb
| What people say | How it's recorded | What Clara does |
|---|---|---|
| The legal entity on the rent check | legalEntity name → two properties | Asks which of the two. |
| A master tenant's name | masterTenant name → the units of one building only | Goes straight to that building. |
| One of several streets around a block | street / nearbyStreet names → one property | Matches the block, however the city numbered it. |
| A street parallel to the main one | nearbyStreet from map data | Matches instead of failing (the real miss that started this). |
| A property's everyday nickname | everyday name from the spreadsheet or the admin page | Matches, even though it's on no sign. |
| A bank-hold "unit" or a do-not-use portfolio | building switched off on the In Propflow switch | Clara doesn't know it exists: never matched, never listed, never named, never counted in occupancy. |
Email uses the same matcher
- Guest cards: the home named in a "New Lead for …" banner is matched in strict mode: an exact name, address or company name only, "Dr" equals "Drive", a trailing unit is ignored. A bare word like "Emerald" is refused instead of guessed.
- Subjects and file names (decided 2026-10-01): whole names only. Joined-up file names are split into words, and one typo is allowed in longer words. Junk such as bounce notices and login alerts stops getting a building.
What we deliberately don't build
- No entity table, no region table, no deeper hierarchy. An LLC or a region is just a name with several targets.
- If one kind ever needs its own attributes (for example a regional manager), we promote that one kind to its own record. The name model stays as it is.
- A region/cluster filter is deferred until real examples justify it.
How we prove it and roll it out
- The matcher's unit tests encode the real edge cases above, plus a replay of the parallel-street miss.
- Multi-turn Clara evals replay real unmatched calls, extending the existing property-matching harness.
- It ships on, with no switch. Until a company's names are entered, the only change a customer hears is that buildings switched off in Propflow disappear. Names arrive through the editor and the two loader scripts, which we run per company.
- Three numbers to watch: match rate, how often she asks, and wrong-match rate. Wrong-match must be zero.
Also in the same audit: per-property and per-company module switches (a self-run property can feed the dashboard with leasing and maintenance off), and dashboard truth (placeholder units out of occupancy, single-family vs multifamily split). They're tracked as rows in the same board phase.
Source: the onboarding call with the client's operations lead and the Gera + Fede standup, both 2026-09-29. Board: portfolio-architecture-phases, phase "Places and names" (rows pn-place-name-records … pn-region-filter). Names updated 2026-09-29 to fit existing code, per Gera's design decisions that day.