Turn vague user searches into conversions in under 100ms.

The Context: ScoutLocal needed users to find the right venue in 1 - 2 taps, from vague queries like "vibey coffee spot," without hiring a full-time search team or blowing up infra costs.

The solution is a Hybrid Search Engine that combines the semantic power of Vector Search (Azure OpenAI) with the precision of SQL filters.

Result: In an early pilot, we validated that users got relevant results from messy queries, while the internal tooling kept strict control over filters, joins, and analytics.

The Problem: Mobile maps typically drain battery and spike API costs by fetching data on every micro-movement.

Result: The architecture was designed and tested to lower map-related API costs and ensure smoother scrolling on mid-range devices once deployed.

In the real world, entities rarely fit into neat boxes. A "Coffee Shop" might also be a "Coffee Roaster" (Maker). Instead of creating three separate accounts, we implemented a Polymorphic Schema.

Performance isn't just about server response times; it's about Perceived Latency. The solution employs an Optimistic UI pattern for high-frequency user actions.

Below are the patterns used to keep vectors and entities in sync, avoiding "ghost" records and race conditions.

1. Backend: Atomic Integrity

await prisma.$transaction(async (tx) => {
    // 1. Reserve Entity ID (Atomic)
    const record = await tx.embedding.create({ ... });

    // 2. External Vector Gen (Rollback on Fail)
    const vector = await openai.embeddings.create({ input: text });

    await tx.embedding.update({ ... });
});

2. Frontend: Optimistic UI

const toggleSave = useCallback(async (id) => {
    // 1. Zero Latency Update
    setSavedIds((prev) => new Set(prev).add(id));

    try {
        await api.post(`/user/saved/${id}`);
    } catch (err) {
        // 2. Self-Healing Rollback
        setSavedIds((prev) => { ... });
        toast.error("Sync failed");
    }
}, []);

3. Identity: Clerk Auth Guard

export async function POST(req: Request) {
  const { userId } = auth(); // Clerk Identity
  if (!userId) return new Response("Unauthorized", { status: 401 });
  
  // Proceed with secure search/sync
  // Merchant isolation is enforced by userId
}