`docs/PLAN.md`

89 lines
# AsSeenInMovies — build plan

## Why
A clean, public-data-only IMDb-class reference for film + TV — facts only,
no IMDb visual assets. Hooks into:
- **thesetdecorator** (61,379-row set-decorator roster, 858 film-pieces, SDSA hub) — shared person + credit data
- **dw_unified.shopify_products** — wallpaper / wallcovering / fabric placements
- **asseeninmovies.com** (this) — SPOTTED feature (products visible in scenes) + premium claim-able profiles

## Hard rules (Steve standing rules)
1. **NEVER use visual assets sourced from IMDb.** Posters/headshots come from TMDB (with required attribution), Wikimedia Commons (CC), public-domain stills, or our `/img/made-with-ai.svg` placeholder.
2. **Public data only.** Facts (titles, dates, names, credits) are public; images aren't.
3. **No DNS / destructive ops / outbound email** during the YOLO loop.
4. **Local LLMs only** for any text generation (Ollama qwen3:14b).
5. **Reversible per tick.**

## Public data sources

### Movies + people (facts)
| Source | Auth | License | Notes |
|---|---|---|---|
| TMDB API v3 | Free key | CC-by-attribution | 50 req/sec, posters available with required "powered by TMDB" attribution. Best primary source. |
| Wikidata SPARQL | None | CC0 | Cross-references TMDB ↔ IMDb ↔ Wikipedia ↔ Wikicommons images. |
| OMDb API | Free key (1000/day) | Free public | Surfaces public Wikipedia/IMDb-derived facts, no IMDb images. |
| MovieLens 25M | Download | Research-friendly | Ratings + tag genomes for 25k+ movies. |
| Library of Congress film | Download | Public domain | Pre-1929 films, fully PD. |
| OpenSubtitles API | Free key | Mixed | Subtitle/dialogue search. |

### Film + TV union directories
| Union | Surface | Reach |
|---|---|---|
| SAG-AFTRA | sagaftra.org/find-actors | ~160k actors, partial public profile |
| DGA | dga.org | ~19k directors + unit dirs / AD's / production mgrs |
| WGA West / East | wgawest.org / wgaeast.org | ~25k writers (West) + ~5k (East) |
| PGA | producersguild.org | ~8k producers |
| AICP | aicp.com | commercials production companies |
| IATSE Local 44 | iatselocal44.org | set decorators / propmakers / leadpersons |
| IATSE Local 600 | cameraguild.com | cinematographers / camera ops |
| IATSE Local 700 | editorsguild.com | picture + sound editors |
| IATSE Local 800 (ADG) | adg.org | production designers / art directors |
| IATSE Local 871 | iatselocal871.org | script supervisors, costumers |
| IATSE Local 891 | iatse.com | many regional locals |
| ACTRA | actra.ca | Canadian actors |
| BAFTA / BFI | bfi.org.uk | British film archive |
| SDSA | setdecorators.org | already imported by thesetdecorator |

### SPOTTED / product-placement sources
| Source | License |
|---|---|
| thesetdecorator film-pieces-seed.json | already ours |
| Heritage Auctions / Profiles in History | public auction lots |
| Studio EPK press kits | press-use OK |
| r/MovieDetails / r/WhatsThisFurnitureFromAITHO | user-submitted, attribution req'd |
| Set-decorator claim submissions | volunteered |
| DW SKU cross-references | internal |

## Tick plan

- **Tick 0 (DONE)** — scaffold project, schema, server, /img/made-with-ai.svg, plan doc.
- **Tick 1** — TMDB ingest: top 1000 movies by popularity → asim_movies, with cross-ref to imdb_id + wikidata_id. Skip poster downloads — store TMDB URL + attribution metadata.
- **Tick 2** — Import thesetdecorator/data/decorator-roster.jsonl (61k rows) → asim_people via asim_people_sources. Tag union_memberships=['iatse-44']. Credits row per movie in their roster.
- **Tick 3** — Wikidata SPARQL enrichment: for each asim_movie, fetch wikidata_id, then film-poster-url-from-commons + cast wikidata Q-IDs. Cache locally.
- **Tick 4** — TMDB cast/crew ingest for the top 1000 movies — populates asim_credits across actors/directors/writers/composers/production-designers/set-decorators.
- **Tick 5** — Public-data SAG-AFTRA actor scrape (rate-limited, structured fields only). Stamp sag_aftra_id + union_memberships=['sag-aftra'].
- **Tick 6** — DGA + WGA public directory imports for directors/writers.
- **Tick 7** — SPOTTED schema bootstrap: import thesetdecorator/data/film-pieces-seed.json (858 rows) into asim_spotted. Match scene→movie via TMDB title search.
- **Tick 8** — `/movie/:id` HTML page (poster grid, credits sorted by department, SPOTTED row).
- **Tick 9** — `/person/:id` HTML page (filmography table, premium badge if claimed).
- **Tick 10** — Premium upgrade tier: Stripe checkout → claim flow → email verification → premium_extras JSONB form (reels URL, current projects, contact form toggle).
- **Tick 11** — SPOTTED submission flow (public form, requires turnstile / email verification).
- **Tick 12** — TMDB top 10k extension. Wikidata enrichment for the next 10k.

## Cross-project hooks
- **thesetdecorator** → shared `asim_people` rows by imdb_id; `asim_people_sources` stores the cross-ref. Both projects read each other's data via SQL views (next tick).
- **dw_unified** → `asim_spotted.dw_sku` joins to `shopify_products` for wallpaper/fabric placements.
- **Big Red** → `asim_*` tables can be queried from Big Red's admin mode for fact-checking ("who decorated the Knives Out set?").

## Ports + processes
- `:9742` — asseeninmovies (Mac2, this project)
- `:9716` — thesetdecorator (Mac2, existing)
- production: bound to `asseeninmovies.com` once tunnel/Kamatera deploy is wired.

## Files
- `server.js` — Express, PG, search/movie/person/spotted endpoints
- `data/schema.sql` — asim_movies, asim_people, asim_credits, asim_spotted, asim_people_sources
- `public/img/made-with-ai.svg` — universal poster/headshot placeholder
- `scrapers/*` — public-data ingest scripts (created per-tick)
- `docs/PLAN.md` — this file