RECORDGOD/RECORDGOD_NAVIGATOR_PLAN.md

RecordGod — Search & Inventory Management (Navigator) port

Faithful port of WowPlatter's Search & Inventory Management workstation onto RecordGod's Postgres + the already-migrated virtual_* geometry. This is the real thing — Store→Rack→Crate→Item drill-down, per-level slot layouts with orientation, scan-to-slot, reorganize, returns, stock finder — NOT the toy /search that ships today (that becomes Phase 0's store view).

Source studied: wowplatter/admin/partials/search.php (844 lines), admin/js/search/main.js (8,482 lines, the live renderer), admin/js/src/navigator/{diagram,scanner,views,state}.js, includes/repositories/class-wowplatter-virtual-store-repository.php, schema-manager virtual tables.

UI rule: light/clean shop-admin theme (see memory recordgod-admin-light-ui), not the dark dash.

---

1. The workstation shape

• Top bar: Space selector (booth-room (default) …), view zoom = Store · Rack · Crate · Item + Auto, level controls ◀ Level 1 of 2 (BOTTOM) ▶, rack-rotate, refresh.
• 5 tabs: Scanner · Returns · Reorganize · Collections · Stock Finder.
• Center: the canvas diagram (changes with the zoom level).
• Right: Crate Contents list (items in the active crate) + collapsible side panels: Quick Insert · Release Info · Crate Info · Rack Info.

The 4 zoom levels are ONE canvas that re-renders:

• Store — top-down room: racks at their positions, doors/portals, compass. Click a rack → Rack.
• Rack — one level of the selected rack (prev/next level), crates laid in slots with an orientation arrow + genre label + slot number, BACK/FRONT/L/R around the rack. Click a crate → Crate.
• Crate — the crate's slot grid (rows×cols from crate_type) + Crate Contents (items by slot_number).
• Item — individual slot/record detail.

---

2. Data model — ALREADY in RecordGod (migrated verbatim by migrate_virtual.py)

Everything below is already in recordgod-db; the work is API + front-end, not schema.

table	the bits that matter
virtual_space	room_width, room_depth, is_default, visible — the room
virtual_rack_type	width, height, depth, panel flags, material; levels via virtual_rack_type_level
virtual_rack_type_level	per-type level rows (level index, shelf height/thickness) — defines how many levels a rack has
virtual_rack	pos_x/pos_y/pos_z, rotation_x/y/z, space_id, rack_type_id, direction (front/back/left/right), genre_ids, style_ids, attach_wall, name
virtual_crate_type	width/height/depth, record_rows, record_columns (the slot grid), material
virtual_crate	rack_id, rack_level_index, crate_type_id, pos_x/y/z (relative to rack origin, m), direction (forward/back/left/right) = the crate's facing, rotation_x/y/z (all 0 in data — IGNORE for facing), layer (upper/lower/floor), name
inventory	crate_id + slot_number — each record's home crate + its slot

Hierarchy: Space → Racks(positioned) → Levels(rack_level_index) → Crates(in slots, oriented) → Items(slot_number).

Genre/style: virtual_rack.genre_ids/style_ids are comma-sep id lists; crate-level tags via a tag table (WowPlatter wowplatter_get_crate_tags). Confirm the migrated tag table name in P2.

Props vs stock (important, every phase): virtual_rack_type.rack_purpose ∈ stock (real record racks) or prop (3D scenery — COLUMNs, AIRCON, STATION, DOOR, couch, trolley…). The functional navigator must filter rack_purpose <> 'prop' everywhere (store-layout already does). type ∈ rack/bench/shelf/'' is the geometry kind, NOT the stock/prop distinction — don't filter on type.

---

3. The geometry, decoded (the tricky x/y/z)

Units. Rack width/depth are cm (/100 = metres, /200 = half). Crate dims + crate pos_* are metres. Rack pos_x/pos_z are room metres.

Facing composes — the slippery bit (confirmed in data 2026-06-22). There are TWO independent direction columns and they STACK:

• virtual_rack.direction ∈ front/back/left/right — which way the whole rack faces in the room.
• virtual_crate.direction ∈ forward/back/left/right — which way THAT crate faces (data: forward 59 / back 57 / left 114 / right 122). This is the facing field — NOT rotation_y (it's 0.0 on every row).
• A crate's world facing = rack.direction ∘ crate.direction. In the rack-level (front-on) view the orientation arrow is the crate's OWN direction in the rack frame; in the store/3D world view you must compose it with the rack's direction or the arrows point the wrong way. Never read one without the other.
• Vocab differs on purpose: crate says forward, rack says front — don't treat the strings as interchangeable.

Render convention (copied from production main.js, do not reinvent):

• directionYaw(dir) → radians: forward/front=0, back=π, left=π/2, right=−π/2. (north/east/south/west alias n=0/e=−π/2-ish via the same table.)
• Crate placement in the rack-level view is by slot_number, not pos_x. Grid: cell=0.34m, cols=floor(rackW/0.34), rows=round(rackD/0.34), slot is 1-indexed row-major; posX=-rackW/2 + cellX/2 + col*cellX, posZ=-rackD/2 + cellZ/2 + row*cellZ. Fall back to pos_x/pos_z only if no slot_number.
• Crate rect yaw = directionYaw(crate.direction) + crate.rotation_y (rotation_y≈0, so direction drives it).
• View-rotation (the rack-rotate button, 0/90/180/270) composes on top: rotatePoint = 90:(-z,x) · 180:(-x,-z) · 270:(z,-x), effective W/D swap at 90/270.
• Facing arrow = rotatedArrows[viewRot][crate.direction], where rotatedArrows[0] = {forward:↓, back:↑, left:←, right:→} and 90/180/270 cycle it. The arrow (not the square) is what the eye reads.
• Edge labels at viewRot 0: BACK top, FRONT bottom, L left, R right — rotate with the view.
• World facing (store/3D view) = directionYaw(rack.direction) + directionYaw(crate.direction) + crate.rotation_y. In the drilldown you're head-on to the rack, so only crate.direction + view-rotation apply.

Store view (renderStoreView, diagram.js):

1. bounds over all racks in the active space (pos ± half), createWorldToCanvas(min,max,pad) → fit+centre.
2. each rack = 4 corners {±halfW,±halfD} → rotatePoint(yaw) → +pos → toCanvas → filled rotated rect + name.
3. portals = door-span line + facing triangle at (x/roomW·W, z/roomD·H), facing_deg; orange=paired, red=unpaired.
4. compass top-right. Hit-test by polygon (pointInPolygon) — crates first, then racks.

Rack view (renderShelfFrontView / renderRackDrilldown): show one rack_level_index at a time. Crates on that level are ordered into slots along the rack width (virtual_crate.pos_x ascending); each slot draws the crate square with: crate id, slot number (sequential), genre label, and an orientation arrow derived from the crate's direction/rotation_y (← → ↑ ↓ = which way the spine faces). BACK/FRONT and L/R labels come from the rack's direction. Level prev/next steps rack_level_index.

Crate view (renderCrateLookupDiagram): a record_rows × record_columns grid (from crate_type); items placed by slot_number; empties dimmed. Crate Contents list = inventory WHERE crate_id=? ordered by slot_number.

---

4. API surface (RecordGod routes ← WowPlatter ajax actions)

All admin-gated, JSON, under /nav/* (new navigator_routes.py). Read side first, then writes.

RecordGod route	replaces ajax	returns / does
GET /nav/spaces	get spaces	the room list for the selector
GET /nav/store-layout?space_id=	get_store_layout	racks (+pos/rot/type/dims) + portals for the store view
GET /nav/rack/{id}	get_rack_details	rack + its levels + crates-per-level (+pos/slot/orientation)
GET /nav/crate/{id}	get_crate_details + get_crate_contents	crate info (name/label/rack/level/last-scanned) + items by slot
GET /nav/crate/{id}/breakdown	get_crate_content_breakdown/analytics	genre/style mix, counts
GET /nav/genres GET /nav/styles	get_all_genres/styles	tag pickers
POST /nav/crate/{id}	save crate	rename / relabel / set genres+styles
POST /nav/rack/{id}	save rack	rename / set genres+styles
POST /nav/scan	scan-to-slot	assign Release IDs/SKUs to a crate's slots sequentially (mode: replace/append)
POST /nav/crate/{id}/compress	compress_crate_slots	close gaps in slot numbering
POST /nav/compress-all	compress_all_crate_slots	compress every crate
POST /nav/reorg	apply_crate_reorganization	move/merge crates between racks/levels; distribute items across slots/crates
GET /nav/collections	get_collections	collection boxes (ties into the Discogs collection-box pricing flow)
GET /nav/stock-finder?q=	stock finder	locate any item → its crate/slot (this is today's /search logic, kept)

inventory writes (crate_id/slot_number) reuse the non-destructive UPSERT rule — never clobber sold/hand-edited rows.

---

5. Front-end

New site/navigator.html (light theme) — replaces /search, keeps the same nav.js top bar. One <canvas> + state.js-style module: { view, spaceId, rackId, levelIndex, crateId }. Port the four renderers from main.js/diagram.js (store / rack-level-slots / crate-grid / item), the polygon hit-test, level prev/next, rack-rotate, and the side panels (Crate Info / Rack Info editors, Release Info, Quick Insert). Workflows: scanner scan-to-slot, returns, reorganize (move/merge/distribute), compress, stock finder. release_id stays the universal key.

---

6. Phases (ship-thin, each usable)

• P0 — store view. /nav/store-layout + the top-down room render (racks at real pos/rot, click a rack). Upgrades today's flat /search map. Zero risk, immediate value.
• P1 — rack drill-down + levels + slots. /nav/rack/{id}; render one level, prev/next, slots with orientation arrows + genre labels. This is the tricky-geometry phase — do it carefully.
• P2 — crate view + info editors. contents by slot, Crate/Rack Info panels (name/label/genre/style/last-scanned), compress slots.
• P3 — Scanner. active crate → scan Release IDs/SKUs → sequential slot assign (replace/append), Test/Process/Clear.
• P4 — Reorganize + Returns. move/merge crates, distribute items across slots; returns back to home crate.
• P5 — Collections + Stock Finder + polish. collection boxes, item view, rack-rotate, the "dope" pass.

Start P0→P1: that already gives a clickable store → rack → level → crate locate, which is the daily driver.

---

6b. Collections + the fallback location map (captured 2026-06-22)

Data already migrated: virtual_collection (14 rows). Model = a named zone: name, color, crate_ids[] (JSON, in click order), priority, sort_method + filing rules genre_ids[] / style_ids[] / label_ids[] / format_descriptions[] / price_min / price_max / year_min / year_max, is_active. Comment in the source: "grouping of crates with filing rules for smart placement." Real examples: 2000s HOUSE = House style + price≥$15 + year 2000–2009 → 12 crates; OLD SCHOOL RAP = year 1980–1986 → 1 crate; BREAKS 15+ = 4 breaks styles + $15+ → 10 crates.

Collections UI (Collections tab): list (colour swatch + crate count) → editor where you click crates on the map and they're kept in click order as removable chips, set name/colour/priority, sort_method (alpha_artist/title, year, price, date_added), filing rules, and a live match panel (N matching · N located · N not located · N overlap). Save → virtual_collection.

THE fallback locator (John's headline ask). GET /nav/locate?release_id= (or sku):

1. exact location first — if the record has crate_id+slot_number, return that.
2. else match the record's genre/style/label/format/price/year against active collections, priority DESC; first hit → return its crate_ids as the "should-be-here" zone ("House $12–15 → these 4 crates"). The match panel's four numbers fall out of this: matching = records a collection's rules select, located = of those, how many actually sit in its crates, not located = match-but-misfiled, overlap = matched by >1 collection.

One data dependency to decide: collections match on discogs genre_ids/style_ids + year, which RecordGod's slim disc_cache doesn't carry (only title/artist/thumb/weight). Options: (a) enrich disc_cache with genre/style/year (backfill from discogs_full on ultra) so the matcher is self-contained — recommended; or (b) denormalise genre/style/year onto inventory at intake. Price is already on inventory.

6c. Reorganize — the A-Z re-file planner (P4)

Server contract (thin; planning is client-side, copy WowPlatter's class-wowplatter-ajax-store-reorg.php):

• POST /nav/reorg/scan {crate_ids[]} → all in-stock items (sku, release_id, crate_id, slot, price, title, artist, year, thumb), ordered crate→slot. (Sources can be crate ids/ranges OR a collection's crates.)
• Client plans: apply filters (price≤ / label / year-range) → pick a distribution target (start crate + count + slots/crate) → sort by sort_method → fill target crates slot-by-slot → produce a move list [{sku, from_crate/slot, to_crate/slot}] + leftovers. Card-by-card walkthrough modal (prev/next, MERGE, Undo).
• POST /nav/reorg/apply {matched[], leftovers[]} → ONE transaction: per sku UPDATE inventory SET crate_id, slot_number, location_updated_*; leftovers → crate_id/slot=NULL, location=archive. Guard SKU-miss → roll back.
• Slot housekeeping: compress_crate_slots (close gaps), insert_with_shift (insert at slot, push others down).

Build order: Collections + fallback locator first (location-map foundation, data already there, every locate benefits), then Reorganize (heavier planner UI). Both reuse the §4 /nav/* router.

7. Open checks before building

1. Confirm virtual_rack_type_level + the crate-tag table actually came across in the migration (column names).
2. Confirm the slot-ordering rule WowPlatter uses (pos_x ascending vs an explicit slot_number on the crate).
3. Crate facing field / composition RESOLVED 2026-06-22 — full render convention captured in §3 ("Render convention"): directionYaw table, slot→grid placement, view-rotation matrix, the rotatedArrows facing table, and the world-facing composition. P1 copies it verbatim.