find

find.elonn.local is the discovery and search service for Elonn. Production is find.elonn.com.

The runtime-facing contract is documented in find-contract.md.

Find owns query records, findings (search results), and heads (classifications). It is distinct from discovery — discovery is the social graph traversal; find is the search service.

Owns

• query records
• findings (computed informational results)
• heads (finding classifications)
• find sessions

Role in the stack

Find produces findings that are surfaced in findings surfaces across runtimes. Findings may be proactive (recommended restaurant, nearby friend) or query-driven (explicit search). Find sessions must always be qualified — do not use "session" alone.

For current implementation status and gaps, see Current State.

Historical milestone note

Status: Historical. Do not use this section as active planning guidance.

Find was a previous platform milestone. The notes below remain only as implementation context:

1. Find query input, provider calls, and normalized finding output.
2. World query relay and action rewriting.
3. Surface creation and persistence of finding surfaces.
4. Web, Android, and iPad loading, empty, error, placement, and refresh states.

Do not conflate Find with Social discovery or Maps field rendering. Before implementation changes, lock down the canonical lifecycle:

query
  -> normalized findings
  -> Surface-created finding surfaces
  -> World composition
  -> runtime rendering and placement persistence

OSM query behavior

• Find does not classify words into categories or place names.
• Nearby sends free-form text to a bounded Nominatim search and enforces the exact 5 km radius.
• Everywhere sends the same free-form text to unrestricted Nominatim.
• term near place resolves the named place globally and applies Nearby there.
• Nearby without an origin returns location_required.
• Find scope is visible and independent of Field controls.

Provider integration boundary

Find owns provider integrations and normalizes provider output before anything downstream receives it. Runtimes, views, and controllers outside Find must not talk directly to Brave, OSM, Nominatim, or Overpass.

The provider flow is:

provider result
  -> finding factory
  -> normalized finding
  -> surface object
  -> runtime

If a provider fails, Find returns empty findings for that provider plus provider error information. It must not inject demo or mocked findings.

Public-web provider status

Brave support is intentionally disabled and is not required for the current Find translation milestone. DuckDuckGo is the next planned public-web provider after the translation boundary is complete.

Readiness

Find exposes GET /ready as its readiness check. It verifies database connectivity, required tables, and OSM reachability before the service is considered ready. Disabled public-web providers do not block readiness.

Key terms

Finding — a discovered or computed informational result. Distinct from notification (targeted, recipient-scoped) and activity (append-only feed record).

Findings surface — a surface composed primarily of findings.

Findings provider — the service generating findings. May be find.elonn.local, maps.elonn.local, or social.elonn.local.

Canonical terms

• find — the search service
• finding — a discovered or computed result
• discovery — the social graph traversal (distinct from find)
• session — always qualify: find session