# STEP 05B — Place Entity Restoration: Audit & Checklist

HEAD: `d6ef412` → this commit. This document is the audit result and the
restoration checklist for the 24 lost Place Entities (10 Temples, 10 Ghats,
4 Kund). **No records were fabricated.** All 24 slots await authentic data
from the administrator.

## 1. Audit findings

### Two-layer data architecture (critical)

The Braj content model has **two distinct layers**, which matters for how the
lost records must be restored:

| Layer | Table | What it holds | Current count |
|-------|-------|---------------|---------------|
| Top-level locations | `places` | Towns (Mathura, Vrindavan, Govardhan, Barsana, Gokul…) **and** famous landmarks (Banke Bihari Temple, Prem Mandir, Vishram Ghat, Radha Kund, Kusum Sarovar…) — seeded by `PlacesSeeder` | 19 (5 with coordinates) |
| Child entities | `place_entities` | Nested Temple / Ghat / Kund / Van / Heritage records belonging to one parent place via `place_id` FK | **0** (the 24 lost here) |

The lost 24 were **child `place_entities`** rows, not the famous landmark
`places`. Those landmark `places` survived because they are recreated by
`PlacesSeeder` during recovery.

### Schema (`place_entities`)

- `place_id` → FK to `places`, `cascadeOnDelete` (entity dies with its place).
- `type` ∈ temple | ghat | kund | van | heritage.
- `latitude` `decimal(10,8)` / `longitude` `decimal(11,8)` — **nullable**.
- `status` default `draft`; `verification_status` default `pending`;
  `is_active` default `true`.
- Public visibility = `status = published` **and** `is_active = true`
  (`PlaceEntity::isPubliclyVisible()`); verification is tracked separately.

### Admin restoration path (reuse existing functionality — no new modules)

- Specialized controllers + forms capture the rich type-specific fields:
  - `Admin\TempleController` → `admin/temples` (deity, temple_type, darshan/aarti timings, timings_verified_on/source…)
  - `Admin\GhatController` → `admin/ghats` (river, ghat_type, bathing_info, rituals, safety_info…)
  - `Admin\KundController` → `admin/kunds` (kund_type, bathing_info…)
- All three accept `place_id` (required, `exists:places,id`) and
  `latitude`/`longitude` as `nullable|numeric|between` — so coordinates can be
  deferred. `verification_status` is required (pending | verified | rejected).
- Duplicate prevention: `slug` must be unique across `place_entities`.

### Public pages

- `/explore/{place}/{type}/{slug}` (generic), plus dedicated
  `/temples/{slug}`, `/ghats/{slug}`, `/kunds/{slug}` detail pages.

### Existing test coverage (already green)

`TempleModuleTest` / `GhatModuleTest` / `KundModuleTest` cover parent
relationship, required parent FK, unique slug, publish→visibility, and
same-place scoping. STEP 05B adds `PlaceEntityRestorationPolicyTest`
(null coordinates allowed, no auto-verify, coordinate range validation).

## 2. Restoration checklist — 24 slots

Every slot below is **AWAITING AUTHENTIC INFORMATION**. The original records'
identities (names, parent places, descriptions) are permanently lost (see
STEP 05A recovery investigation) and were **not** recoverable from any source.
They are intentionally left blank rather than invented.

Fill each row from an authoritative source (temple board, official site,
administrator's own records) before creating the record. **Coordinates must
be verified** — if unverified, leave them blank (the schema permits null) and
do not substitute the parent town's coordinates.

### Temples (10 slots)

| # | Name | हिंदी नाम | Parent place | Deity | Verified lat,lng | Source | Status |
|---|------|----------|--------------|-------|------------------|--------|--------|
| T1 | _awaiting input_ | | | | | | not created |
| T2 | _awaiting input_ | | | | | | not created |
| T3 | _awaiting input_ | | | | | | not created |
| T4 | _awaiting input_ | | | | | | not created |
| T5 | _awaiting input_ | | | | | | not created |
| T6 | _awaiting input_ | | | | | | not created |
| T7 | _awaiting input_ | | | | | | not created |
| T8 | _awaiting input_ | | | | | | not created |
| T9 | _awaiting input_ | | | | | | not created |
| T10 | _awaiting input_ | | | | | | not created |

### Ghats (10 slots)

| # | Name | हिंदी नाम | Parent place | River | Verified lat,lng | Source | Status |
|---|------|----------|--------------|-------|------------------|--------|--------|
| G1 | _awaiting input_ | | | | | | not created |
| G2 | _awaiting input_ | | | | | | not created |
| G3 | _awaiting input_ | | | | | | not created |
| G4 | _awaiting input_ | | | | | | not created |
| G5 | _awaiting input_ | | | | | | not created |
| G6 | _awaiting input_ | | | | | | not created |
| G7 | _awaiting input_ | | | | | | not created |
| G8 | _awaiting input_ | | | | | | not created |
| G9 | _awaiting input_ | | | | | | not created |
| G10 | _awaiting input_ | | | | | | not created |

### Kunds (4 slots)

| # | Name | हिंदी नाम | Parent place | Verified lat,lng | Source | Status |
|---|------|----------|--------------|------------------|--------|--------|
| K1 | _awaiting input_ | | | | | not created |
| K2 | _awaiting input_ | | | | | not created |
| K3 | _awaiting input_ | | | | | not created |
| K4 | _awaiting input_ | | | | | not created |

## 3. Overlap warning — do not duplicate seeded landmarks

`PlacesSeeder` already creates famous Braj landmarks as top-level `places`
(e.g. Banke Bihari Temple, Prem Mandir, Krishna Janmabhoomi, Dwarkadhish
Temple, ISKCON, Radha Raman Temple, Nidhivan, Govardhan Hill, Vishram Ghat,
Radha Kund, Shyam Kund, Kusum Sarovar). Before restoring any entity, confirm
it is **not** a duplicate of one of these `places`. If the 24 lost child
entities were actually redundant with these landmark places, the correct
outcome may be to restore **fewer than 24** — authenticity outranks the count.

## 4. Restoration rules (per policy)

1. Create through the existing admin UI (`/admin/.../temples|ghats|kunds/create`)
   with the existing permissions — no new modules, no manual SQL.
2. Names, Hindi names, parent place, descriptions only from reliable sources
   or administrator-confirmed data.
3. Coordinates from a reliable source or confirmed administrator input; if
   unverified, leave empty (schema allows null) — **never** place an entity at
   its parent town's coordinates as a substitute.
4. Keep `verification_status = pending` until verification actually happens;
   do not mark Verified on creation.
5. Take a backup before any bulk data change; verify the resolved database is
   the development DB for manual entry and that automated tests stay on
   `dham_seva_test` (see `docs/database-safety.md`).

## 5. Map integration (once coordinates exist)

Eligible Temple/Ghat/Kund records with **real, valid** coordinates can appear
as separate map markers where the architecture supports it. The STEP 05 map
currently plots `places` only; entity markers are a follow-up that must keep
the real-coordinates-only rule. Parent-town coordinates stay separate from
individual entity coordinates.

## 6. Outcome of STEP 05B

### 6a. Overlap resolved — 13 landmark Places reclassified into entities

Following the administrator's decision (Option B), the 13 famous landmark
Places were moved into the typed `place_entities` layer under their parent
town, and the original Places were **archived (soft-deleted, restorable — not
destroyed)**. This removed the duplicate representation while keeping the
rich temple/ghat/kund content in the layer the architecture intends.

Reversible via: `php artisan places:reclassify --reverse`.

| Entity type | Count | Records (parent town) |
|-------------|-------|-----------------------|
| temple | 6 | Krishna Janmabhoomi, Dwarkadhish (Mathura); Banke Bihari, ISKCON, Prem Mandir, Radha Raman (Vrindavan) |
| ghat | 1 | Vishram Ghat (Mathura) |
| kund | 3 | Radha Kund, Shyam Kund, Kusum Sarovar (Govardhan) |
| van | 2 | Nidhivan, Seva Kunj (Vrindavan) |
| heritage | 1 | Govardhan Hill (Govardhan) |

- All 13: `status=published`, `verification_status=pending`, **coordinates NULL**
  (landmark Places carried none and inventing them is prohibited).
- Old `/places/{slug}` URLs **301-redirect** to the entity pages (no broken links).
- **Nandgaon excluded** — it is a town, not a child entity (separate data-quality
  item: it lacks the verified coordinates/region the other towns have).
- Remaining visible `places`: the 5 region-linked towns + Nandgaon (6 total).

### 6b. The 24 originally-lost manual entities

These were a separate, manually-created set of child `place_entities` whose
identities are permanently lost (see STEP 05A) and were **not** recoverable.
They were **not** fabricated. Their most famous counterparts now exist as the
13 reclassified entities above; whether additional (lesser-known) entities are
needed is an administrator decision requiring authentic data. The 24-slot
checklist in §2 remains the template for entering any confirmed records.

### 6c. Verification

- Live: all entity pages 200 (`/temples/*`, `/ghats/*`, `/kunds/*`,
  `/explore/{town}/vans/*`, `/explore/{town}/important-places/*`); old
  `/places/{slug}` 301 → entity page; `/explore`, `/map`, `/84-kos` 200.
- Full regression suite green on the isolated test database.

## 7. STEP 05C — Entity data enrichment

Coordinates (and temple deity) populated from a **reliable source — English
Wikipedia** via its REST summary API, reviewed and sanity-checked against the
Braj bounding box. Reversible via `php artisan entities:enrich --clear-coords`.

**Verification is untouched:** every record stays `verification_status = pending`.
Populating a field never auto-marks a record Verified; the admin confirms and
flips it after real review (admin forms now expose latitude/longitude inputs
for correction).

### Confirmed coordinates vs still-missing

**11 of 13 entities have confirmed coordinates** (source: Wikipedia):

| Entity | Type | lat, lng | Source |
|--------|------|----------|--------|
| Krishna Janmabhoomi | temple | 27.504748, 77.669754 | Wikipedia |
| Dwarkadhish Temple | temple | 27.5051227, 77.6850175 | Wikipedia |
| Banke Bihari Temple | temple | 27.57976, 77.69051 | Wikipedia |
| ISKCON Temple Vrindavan | temple | 27.57241945, 77.67775279 | Wikipedia |
| Prem Mandir | temple | 27.5724569, 77.6724919 | Wikipedia |
| Radha Raman Temple | temple | 27.58537083, 77.69876667 | Wikipedia |
| Vishram Ghat | ghat | 27.51265028, 77.68701306 | Wikipedia |
| Radha Kund | kund | 27.525278, 77.491389 | Wikipedia |
| Kusum Sarovar | kund | 27.51218333, 77.47766944 | Wikipedia |
| Nidhivan | van | 27.583269, 77.697643 | Wikipedia |
| Govardhan Hill | heritage | 27.51053611, 77.47610556 | Wikipedia |

**2 of 13 still NULL** (no reliable own source — left empty, never substituted):

| Entity | Type | Why NULL |
|--------|------|----------|
| Seva Kunj | van | No English Wikipedia article with coordinates. |
| Shyam Kund | kund | Only the adjacent Radha Kund had coordinates; Shyam Kund is a distinct kund and its point was not substituted. |

### Deity (temples only, well-established from Wikipedia)

Krishna Janmabhoomi → Lord Krishna; Dwarkadhish → Lord Krishna (Dwarkadhish);
Banke Bihari → Banke Bihari (Radha-Krishna); ISKCON → Lord Krishna;
Prem Mandir → Lord Krishna; Radha Raman → Radha Raman (Lord Krishna).

Darshan timings, aarti schedules, history and bathing details were **left
pending** — these are volatile or prose fields best entered by the admin from
a verified source (the admin forms already capture them, with a
`timings_verified_on` / `timings_source` provenance pair).

### Map integration

`/map` now renders **entity markers using each entity's OWN valid coordinates**
(the parent town's are never substituted). Entities without coordinates appear
in the honest "Location not available on map" list, never as fake pins. The
STEP 05 map keeps its real-coordinates-only rule.

---

## 8. STEP 08 — Geographic Data Completion & Verification

Current HEAD: `7b8630b`. Objective: improve geographic data quality for Seva Kunj,
Shyam Kund and Nandgaon without fabricating coordinates or changing unrelated
features.

### 8.1 Audit findings (before STEP 08)

| Record | Type | Parent place | latitude | longitude | verification_status | Region links |
|--------|------|--------------|----------|-----------|---------------------|--------------|
| Seva Kunj | van | Vrindavan | NULL | NULL | pending | 1 (via place) |
| Shyam Kund | kund | Govardhan | NULL | NULL | pending | 1 (via place) |
| Radha Kund | kund | Govardhan | 27.525278 | 77.491389 | pending | 1 (via place) |
| Nandgaon (town) | place | — | NULL | NULL | pending | 0 |

Nandgaon is a **town/place** (not a child entity). It is deliberately absent from
the `BrajRegionSeeder` area list (which covers only vrindavan, mathura, govardhan,
barsana, gokul), so it has no region link. Per STEP 08, the five-region hierarchy
is NOT assumed complete and no region was invented for Nandgaon.

### 8.2 Source verification (English Wikipedia REST summary API)

| Record | Sought | Result | Decision |
|--------|--------|--------|----------|
| Seva Kunj | `Seva Kunj` | HTTP 404 — no English Wikipedia article | Coordinates left **NULL**. Never substituted from Nidhivan or Vrindavan. |
| Shyam Kund | `Shyam Kund` | HTTP 404 — no English Wikipedia article | Coordinates left **NULL**. Never substituted from adjacent Radha Kund (a distinct kund). |
| Nandgaon | `Nandgaon, Uttar Pradesh` | `coordinates.lat=27.72, lon=77.38` | Applied to `places.latitude/longitude`. Within Braj bbox (27.3–27.8 N, 77.2–77.8 E). |

Source URLs consulted:
- https://en.wikipedia.org/api/rest_v1/page/summary/Seva_Kunj (404)
- https://en.wikipedia.org/api/rest_v1/page/summary/Shyam_Kund (404)
- https://en.wikipedia.org/api/rest_v1/page/summary/Nandgaon,_Uttar_Pradesh (200, coordinates)

### 8.3 Data changes applied (dev `dham_seva_db`)

- **Nandgaon**: `latitude=27.72`, `longitude=77.38` (Wikipedia). `verification_status` intentionally left `pending` — a populated field never auto-marks a record Verified.
- **Seva Kunj**: unchanged (`NULL`/`NULL`, `pending`).
- **Shyam Kund**: unchanged (`NULL`/`NULL`, `pending`).
- Backup taken before change: `backups/dham_seva_db_STEP08-pre_20261017_121833.sql` (553 KB, 53 tables).
- No records created, deleted, or truncated. No migration. No unrelated feature touched.

### 8.4 Remaining gaps (reported, not invented)

- Seva Kunj and Shyam Kund have no reliable own-coordinate source; they stay NULL and appear in the honest "Location not available on map" list. They remain selectable in `/planner` but are not plotted or measured.
- Nandgaon has no region link. The administrator should confirm the correct region association (or add a Nandgaon area region) from a reliable source; this STEP deliberately does not assume one.

