`docs/vision.md`

91 lines
# Product vision — the universe around the address

The core navigational unit is the **address**, but every address is a
hub in a graph. Click an address → see everyone and everything that
ever intersected that place. Click a person → see every address they
ever lived at, owned, designed, tenanted.

## The address page (free tier)

Hero: building photo + canonical address + jurisdiction badge.
Below the fold, the timeline:

- **Built** (year, architect if known, original use)
- **Permits** (chronological, linkable, each with source + date)
- **Sales ledger** (recorded transfers, each anchored to a deed source)
- **Business occupants** (for commercial addresses: who was here, when)
- **People associated** (historical only, each with source tier badge)
- **Archival media** (Sanborn maps by decade, HABS/HAER photos, archive stills)
- **Rental projection** (derived from the 1978-1984 LA multiplier — see rent-multiplier-1978-1984.md)

Every item on the page carries its `source_tier` dot (A/B/C/D) so the
reader instantly knows what is a government record vs. a verified
secondary vs. a lead under review.

## The person page (free tier)

Hero: archival portrait + name + vital years.
Below: the person's address graph —

- A map pinning every historically verified address (pilot: Beverly Hills)
- A timeline: date ranges at each address, overlapping if applicable
- Relation chips: `resident` · `owner` · `designer` · `tenant`
- Related people: others verifiably associated with the same addresses
- Source ledger: every claim's tier, URL, reviewer

The same source_tier + date_range rules apply. Nothing about a living
person with an unended or recent association is publicly visible —
the privacy trigger (`epa_privacy_gate`) enforces this at the database
level, not just the UI.

## The "click-through" that makes the product

```
 Address page ─► People associated (click) ─► Person page
                                               ├─► another Address (click)
                                               │    └─► another Person (click)
                                               │         └─► ...
                                               └─► decade timeline
```

This is what the research report called "graph edges for stories."
Same `place_id` ↔ `entity_id` links power:

- The free public page
- The claim-to-upgrade upsell ("this is the home; here's who lived here;
  now claim and customize.")
- An API object for enterprise (real estate, historic preservation,
  film-location scouts)

## What the claim + $9.99 unlocks

On the claim flow:
- Add photos (today and historical they own rights to)
- Add booking URL, contact info, custom copy
- **Curate** the people/association list on their own address
  (approve / re-order / mark primary — never publish a new living
  association; the DB trigger blocks that)
- Custom domain option (pro tier)
- Hosting included in $9.99

## Privacy posture (non-negotiable)

- `entity.is_living = true` + `date_to IS NULL or > today - 25yr`
  → association CANNOT be public, trigger raises
- No current-address inference from paparazzi/social
- Source tier D (social/lead) never renders on the public page;
  it's editorial queue only
- Current celebrity residences are out of scope on principle, not
  just due to a schema check

## Pilot geography

Beverly Hills first:
- Small, well-documented
- City of Beverly Hills nightly permit feed
- Beverly Hills Public Library archival collection
- Sanborn coverage strong for the era we care about

Expand outward in concentric rings as ingestion stabilizes: Beverly
Hills → West Hollywood → Hollywood → broader LA County.