feat(places): promote confirmed OSM venue picks into the places catalogue (#119)

## Summary

- Closes the remaining "search *and creation*" gap from the earlier
investigation (#118, merged): `geocodeAddress` already searched
`places.places` first and fell back to Nominatim, but a Nominatim hit
was used for exactly one event and then forgotten — it never got
promoted into the DB catalogue, so the next search for the same venue
hit Nominatim again instead of the (much faster, richer) DB tier.
- `ensurePlaceFromOsmSuggestion` now runs when a host confirms an
OSM/Nominatim suggestion in the location picker (`LocationModal`). It's
idempotent (keyed on `sourceProvenance.legacyId`, the same convention
the platform's own OSM ingestion pipeline uses — verified against live
sample docs), enriches the pick via a single-element Overpass API lookup
to infer a `placeType` from the closed enum, and writes a paired
external/organization entity alongside the place (every place needs an
entity owner per the validator).
- Both document shapes were verified directly against the real
production `places`/`entity` Atlas validators (insert → confirm accepted
→ delete) before wiring this up, since a malformed write to a
platform-owned schema is expensive to get wrong.

## Type of Change

- [x] New feature (non-breaking change that adds functionality)

## Changes

- `src/app/actions/geocode.ts` — `ensurePlaceFromOsmSuggestion`,
`fetchOverpassTags` (Overpass single-element tag lookup),
`inferPlaceType` (OSM tag → `PlaceDoc.placeType` enum mapping),
`osmType`/`osmId` added to `GeocodeSuggestion`.
- `src/components/ui/address-autocomplete.tsx` — carries
`source`/`osmType`/`osmId` through `AddressComponents`.
- `src/components/modals/location-modal.tsx` — calls
`ensurePlaceFromOsmSuggestion` (fire-and-forget) when an OSM-sourced
suggestion is confirmed.
- `src/app/actions/geocode.test.ts` — idempotency, successful create +
tag-based `placeType` inference, Overpass-unreachable fallback, and
never-throws coverage.

## Test Plan

- [x] Existing tests pass (`npm run test:run` — 792 passed)
- [x] New tests added for this change (`ensurePlaceFromOsmSuggestion`: 4
new cases)
- [x] Lint passes (`npm run lint`)
- [x] Build succeeds (`npm run build`)
- [x] Manual testing performed — both the entity and place document
shapes were inserted into the real production collections, confirmed
accepted by the Atlas JSON-Schema validators, then deleted immediately
(no test data left behind)

## Checklist

- [x] My code follows the project's code conventions
- [x] I have added tests that cover my changes
- [x] This PR has a clear, focused scope (one feature, following on from
#118)


---
_Generated by [Claude
Code](https://claude.ai/code/session_01Sn4ULkV3dFFxEq5x3nCdaX)_

Author: bryanfawcett

src/app/actions/geocode.test.ts

@@ -3,11 +3,13 @@ import { describe, it, expect, vi, beforeEach } from "vitest";
 vi.mock("server-only", () => ({}));
 
 // Mongo accessor + auth gate are mocked so the action runs in isolation.
-const places = { find: vi.fn(), aggregate: vi.fn() };
+const places = { find: vi.fn(), aggregate: vi.fn(), findOne: vi.fn(), insertOne: vi.fn() };
 const placesGeo = { findOne: vi.fn() };
+const entities = { insertOne: vi.fn() };
 vi.mock("@/lib/mongo/databases", () => ({
   placesCollection: vi.fn(async () => places),
   placesGeoCollection: vi.fn(async () => placesGeo),
+  entitiesCollection: vi.fn(async () => entities),
 }));
 vi.mock("@workos-inc/authkit-nextjs", () => ({
   withAuth: vi.fn(async () => ({ user: { id: "user_1" } })),
@@ -16,7 +18,7 @@ vi.mock("@/lib/auth/dev", () => ({
   isDevBypass: vi.fn(() => true),
 }));
 
-import { geocodeAddress, reverseGeocode, resolveCountryTimezone } from "./geocode";
+import { geocodeAddress, reverseGeocode, resolveCountryTimezone, ensurePlaceFromOsmSuggestion } from "./geocode";
 
 /** Build a chainable find() result (.limit().toArray()). */
 function findReturning(docs: unknown[]) {
@@ -41,6 +43,9 @@ beforeEach(() => {
   // Simulate Atlas Search being unavailable by default (e.g. no index on a
   // local/test cluster) so existing regex-path tests keep exercising find().
   places.aggregate.mockReturnValue(aggregateReturning(new Error("no such index")));
+  places.findOne.mockResolvedValue(null);
+  places.insertOne.mockResolvedValue({ acknowledged: true });
+  entities.insertOne.mockResolvedValue({ acknowledged: true });
   placesGeo.findOne.mockResolvedValue(null);
   global.fetch = vi.fn();
 });
@@ -306,3 +311,74 @@ describe("resolveCountryTimezone", () => {
     expect(await resolveCountryTimezone("Nowhere")).toBeUndefined();
   });
 });
+
+describe("ensurePlaceFromOsmSuggestion", () => {
+  const input = {
+    name: "Miekles Hotel",
+    address: "Jason Moyo Avenue",
+    city: "Harare",
+    country: "Zimbabwe",
+    latitude: -17.8303379,
+    longitude: 31.0527331,
+    osmType: "way",
+    osmId: 136597457,
+  };
+
+  it("is a no-op (returns the existing id) when the OSM element is already catalogued", async () => {
+    places.findOne.mockResolvedValue({ _id: "existing-place-1" });
+
+    const id = await ensurePlaceFromOsmSuggestion(input);
+
+    expect(places.findOne).toHaveBeenCalledWith({ "sourceProvenance.legacyId": "way/136597457" });
+    expect(id).toBe("existing-place-1");
+    expect(places.insertOne).not.toHaveBeenCalled();
+    expect(entities.insertOne).not.toHaveBeenCalled();
+  });
+
+  it("creates a paired external entity + place, inferring placeType from Overpass tags", async () => {
+    (global.fetch as ReturnType<typeof vi.fn>).mockResolvedValue({
+      ok: true,
+      json: async () => ({ elements: [{ type: "way", id: 136597457, tags: { tourism: "hotel", name: "Miekles Hotel" } }] }),
+    });
+
+    const id = await ensurePlaceFromOsmSuggestion(input);
+
+    expect(id).toEqual(expect.any(String));
+    expect(entities.insertOne).toHaveBeenCalledTimes(1);
+    const entityDoc = entities.insertOne.mock.calls[0][0];
+    expect(entityDoc).toMatchObject({
+      entityType: "organization",
+      ecosystemRole: "external",
+      name: "Miekles Hotel",
+      primaryPlaceId: id,
+      sourceProvenance: { legacyId: "way/136597457", mirroredFrom: "osm" },
+    });
+
+    expect(places.insertOne).toHaveBeenCalledTimes(1);
+    const placeDoc = places.insertOne.mock.calls[0][0];
+    expect(placeDoc).toMatchObject({
+      _id: id,
+      ownerEntityId: entityDoc._id,
+      name: "Miekles Hotel",
+      placeType: ["Accommodation"],
+      geo: { type: "Point", coordinates: [31.0527331, -17.8303379] },
+      sourceProvenance: { legacyId: "way/136597457", dataOrigin: "osm" },
+    });
+  });
+
+  it("falls back to a generic LocalBusiness placeType when Overpass is unreachable", async () => {
+    (global.fetch as ReturnType<typeof vi.fn>).mockRejectedValue(new Error("network down"));
+
+    await ensurePlaceFromOsmSuggestion(input);
+
+    const placeDoc = places.insertOne.mock.calls[0][0];
+    expect(placeDoc.placeType).toEqual(["LocalBusiness"]);
+  });
+
+  it("never throws — swallows a Mongo write failure and returns null", async () => {
+    places.insertOne.mockRejectedValue(new Error("insert failed"));
+    (global.fetch as ReturnType<typeof vi.fn>).mockResolvedValue({ ok: true, json: async () => ({ elements: [] }) });
+
+    await expect(ensurePlaceFromOsmSuggestion(input)).resolves.toBeNull();
+  });
+});

src/app/actions/geocode.ts

@@ -24,9 +24,10 @@
 
 import { withAuth } from "@workos-inc/authkit-nextjs";
 import tzlookup from "tz-lookup";
-import { placesCollection, placesGeoCollection } from "@/lib/mongo/databases";
+import { placesCollection, placesGeoCollection, entitiesCollection } from "@/lib/mongo/databases";
 import { isDevBypass } from "@/lib/auth/dev";
-import type { PlaceDoc } from "@/lib/mongo/types";
+import { newId, slugify, stampNew } from "@/lib/mongo/ids";
+import type { PlaceDoc, EntityDoc } from "@/lib/mongo/types";
 
 export interface GeocodeSuggestion {
   /** Where the row came from — DB hits are surfaced above OSM hits. */
@@ -47,6 +48,11 @@ export interface GeocodeSuggestion {
   longitude: number;
   /** IANA timezone resolved from the coordinates (e.g. "Africa/Harare"). */
   timezone?: string;
+  /** OSM element type/id backing an `source: "osm"` suggestion — used to
+   *  promote a selected suggestion into the `places.places` catalogue via
+   *  `ensurePlaceFromOsmSuggestion`. Absent for `source: "db"` rows. */
+  osmType?: string;
+  osmId?: number;
 }
 
 /** Resolve an IANA timezone from coordinates; `tzlookup` throws on out-of-range input. */
@@ -66,6 +72,8 @@ const NOMINATIM_ENDPOINT = "https://nominatim.openstreetmap.org";
 // could contact. Kept generic (no PII) but app-specific.
 const NOMINATIM_USER_AGENT = "nhimbe/1.0 (+https://nhimbe.com; events discovery)";
 
+const OVERPASS_ENDPOINT = "https://overpass-api.de/api/interpreter";
+
 const DEFAULT_LIMIT = 6;
 const MIN_QUERY_LENGTH = 3;
 
@@ -222,11 +230,11 @@ function mapNominatimFeature(f: NominatimFeature): GeocodeSuggestion | null {
   const street = [addr.house_number, addr.road].filter(Boolean).join(" ");
   const name = props.name || street || city || (props.display_name ?? "").split(",")[0] || "";
   const osmType = props.osm_type ?? "node";
-  const osmId = props.osm_id ?? "";
+  const osmIdNum = Number(props.osm_id);
 
   return {
     source: "osm",
-    placeId: `osm:${osmType}/${osmId}`,
+    placeId: `osm:${osmType}/${props.osm_id ?? ""}`,
     name,
     address: street,
     city,
@@ -235,6 +243,8 @@ function mapNominatimFeature(f: NominatimFeature): GeocodeSuggestion | null {
     latitude: lat,
     longitude: lng,
     timezone: timezoneForCoords(lat, lng),
+    osmType,
+    osmId: Number.isFinite(osmIdNum) ? osmIdNum : undefined,
   };
 }
 
@@ -378,3 +388,140 @@ export async function resolveCountryTimezone(country: string): Promise<string |
   if (!ll) return undefined;
   return timezoneForCoords(ll[0], ll[1]);
 }
+
+/**
+ * Fetch a single OSM element's raw tags from the Overpass API — a targeted
+ * single-element lookup (fast, not a wide search), used to enrich a
+ * Nominatim hit with the same category/amenity data the Mukoko platform's own
+ * OSM ingestion pipeline reads before promoting it into `places.places`.
+ */
+async function fetchOverpassTags(osmType: string, osmId: number): Promise<Record<string, string> | null> {
+  const kind = osmType === "way" || osmType === "relation" ? osmType : "node";
+  try {
+    const res = await fetch(OVERPASS_ENDPOINT, {
+      method: "POST",
+      body: `data=${encodeURIComponent(`[out:json][timeout:10];${kind}(${osmId});out tags;`)}`,
+      headers: { "Content-Type": "application/x-www-form-urlencoded" },
+      next: { revalidate: 86400 },
+    });
+    if (!res.ok) return null;
+    const body = (await res.json()) as { elements?: Array<{ tags?: Record<string, string> }> };
+    return body.elements?.[0]?.tags ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/** `places.places.placeType` is a closed enum — map common OSM tags onto it. */
+function inferPlaceType(tags: Record<string, string> | null): PlaceDoc["placeType"] {
+  if (!tags) return ["LocalBusiness"];
+  const tourism = tags.tourism;
+  const amenity = tags.amenity;
+  if (tourism && ["hotel", "guest_house", "motel", "hostel", "apartment", "chalet"].includes(tourism)) {
+    return ["Accommodation"];
+  }
+  if (tourism && ["attraction", "museum", "viewpoint", "artwork", "gallery", "zoo"].includes(tourism)) {
+    return ["TouristAttraction"];
+  }
+  if (amenity && ["restaurant", "cafe", "fast_food", "bar", "pub", "food_court"].includes(amenity)) {
+    return ["Restaurant"];
+  }
+  if (tags.shop) return ["Store"];
+  if (tags.leisure === "park" || tags.leisure === "nature_reserve") return ["Park"];
+  if (tags.natural === "beach") return ["Beach"];
+  if (tags.natural === "peak" || tags.natural === "volcano") return ["Mountain"];
+  if (tags.natural === "water" && tags.water === "lake") return ["Lake"];
+  if (tags.waterway === "river") return ["River"];
+  if (
+    amenity &&
+    ["townhall", "courthouse", "police", "fire_station", "embassy", "public_building"].includes(amenity)
+  ) {
+    return ["CivicStructure"];
+  }
+  if (tags.building === "residential" || tags.building === "house" || tags.building === "apartments") {
+    return ["Residence"];
+  }
+  return ["LocalBusiness"];
+}
+
+export interface EnsurePlaceInput {
+  name: string;
+  address: string;
+  city: string;
+  country: string;
+  latitude: number;
+  longitude: number;
+  osmType: string;
+  osmId: number;
+}
+
+/**
+ * Promote a confirmed OSM/Nominatim venue selection into the `places.places`
+ * catalogue (closing the "search then creation" loop) so the NEXT search for
+ * the same venue hits the DB tier instead of Nominatim again.
+ *
+ * Idempotent — keyed on `sourceProvenance.legacyId` (`"<osmType>/<osmId>"`,
+ * the same key the platform's own OSM ingestion pipeline uses), so re-picking
+ * the same venue never inserts a duplicate. Per the `places.places` /
+ * `entity.entities` validators (Rule 10 — every place has an entity owner),
+ * this writes a paired external/organization entity alongside the place,
+ * mirroring the shape already used by every OSM-sourced row in the catalogue
+ * today (confirmed against a live sample via the Mongo/MCP inspection this
+ * function grew out of). Best-effort: never throws, so a catalogue-write
+ * failure never blocks the caller from finishing whatever they were doing
+ * (e.g. selecting a venue for an event).
+ */
+export async function ensurePlaceFromOsmSuggestion(input: EnsurePlaceInput): Promise<string | null> {
+  try {
+    await assertCaller();
+    const places = await placesCollection();
+    const legacyId = `${input.osmType}/${input.osmId}`;
+
+    const existing = await places.findOne({ "sourceProvenance.legacyId": legacyId });
+    if (existing) return existing._id;
+
+    const tags = await fetchOverpassTags(input.osmType, input.osmId);
+    const placeType = inferPlaceType(tags);
+
+    const entities = await entitiesCollection();
+    const entityId = newId();
+    const placeId = newId();
+
+    const entityDoc = {
+      ...stampNew(entityId),
+      entityType: "organization",
+      ecosystemRole: "external",
+      schemaOrgType: "LocalBusiness",
+      slug: slugify(input.name),
+      name: input.name,
+      isActive: true,
+      isPrivateByDefault: false,
+      primaryPlaceId: placeId,
+      sourceProvenance: { legacyId, mirroredFrom: "osm", sourceProject: "nhimbe" },
+    } as EntityDoc;
+    await entities.insertOne(entityDoc);
+
+    const placeDoc = {
+      ...stampNew(placeId),
+      ownerEntityId: entityId,
+      slug: slugify(input.name),
+      name: input.name,
+      isActive: true,
+      placeType,
+      geo: { type: "Point", coordinates: [input.longitude, input.latitude] },
+      address: {
+        "@type": "PostalAddress",
+        streetAddress: input.address,
+        addressLocality: input.city,
+        addressCountry: input.country,
+      },
+      sourceProvenance: { legacyId, dataOrigin: "osm", dataConfidence: 0.6 },
+    } as PlaceDoc;
+    await places.insertOne(placeDoc);
+
+    return placeId;
+  } catch (e) {
+    console.error("[mukoko] ensurePlaceFromOsmSuggestion failed", e);
+    return null;
+  }
+}

src/components/modals/location-modal.tsx

@@ -7,7 +7,7 @@ import { Input } from "@/components/ui/input";
 import { Button } from "@/components/ui/button";
 import { Label } from "@/components/ui/label";
 import { ResponsiveModal } from "@/components/ui/responsive-modal";
-import { resolveCountryTimezone } from "@/app/actions/geocode";
+import { resolveCountryTimezone, ensurePlaceFromOsmSuggestion } from "@/app/actions/geocode";
 import { timezoneLabel } from "@/lib/timezone";
 
 function isValidMeetingUrl(value: string): boolean {
@@ -158,6 +158,27 @@ export function LocationModal({
                   } else {
                     setSelectedTimezone(null);
                   }
+                  // Promote a confirmed OSM/Nominatim pick into the places
+                  // catalogue so the next search for this venue hits the DB
+                  // tier first — best-effort, fire-and-forget.
+                  if (
+                    components.source === "osm" &&
+                    components.osmType &&
+                    components.osmId !== undefined &&
+                    components.latitude !== undefined &&
+                    components.longitude !== undefined
+                  ) {
+                    ensurePlaceFromOsmSuggestion({
+                      name: components.venue,
+                      address: components.address,
+                      city: components.city,
+                      country: components.country,
+                      latitude: components.latitude,
+                      longitude: components.longitude,
+                      osmType: components.osmType,
+                      osmId: components.osmId,
+                    });
+                  }
                 }}
                 placeholder="Search for a venue or address..."
               />

src/components/ui/address-autocomplete.tsx

@@ -27,6 +27,11 @@ interface AddressComponents {
   longitude?: number;
   /** IANA timezone resolved from the selected coordinates (e.g. "Africa/Harare"). */
   timezone?: string;
+  /** Set only for `source: "osm"` picks — lets the caller promote the
+   *  selection into the places catalogue via `ensurePlaceFromOsmSuggestion`. */
+  source?: "db" | "osm";
+  osmType?: string;
+  osmId?: number;
 }
 
 interface AddressAutocompleteProps {
@@ -125,6 +130,9 @@ export function AddressAutocomplete({
         latitude: s.latitude,
         longitude: s.longitude,
         timezone: s.timezone,
+        source: s.source,
+        osmType: s.osmType,
+        osmId: s.osmId,
       });
       onChange(s.displayName);
       setSuggestions([]);