DEV Community

Cover image for What If Your City Was Hiding Secrets? I Built WAYBOUND to Find Them.
Arun Yadav
Arun Yadav

Posted on

What If Your City Was Hiding Secrets? I Built WAYBOUND to Find Them.

#hf26challenge #devchallenge #ai #opensource

Hacktoberfest Open-Source AI Challenge Week 1: Touch Grass Submission 🌿

This is a submission for the Hacktoberfest Open-Source AI Challenge Week 1: Touch Grass

What I Built

WAYBOUND is an AI-powered, location-based mystery adventure platform that transforms ordinary neighborhood walks into immersive, clue-driven expeditions through real public places.

Open the app. Share your location. Receive a mystery. Walk toward it.

The app uses your real GPS coordinates to discover genuinely nearby public landmarks via Google Places API, then hands that real-world data to an open-weight Google Gemma 2 AI to generate a unique narrative mission: a title, progressive riddle clues, and a hidden destination revealed only when you physically arrive.

Who is it for? Anyone who's walked the same routes for years and suspects their city is more interesting than their daily commute suggests. It's built for curious pedestrians, urban explorers, families looking for structured outdoor adventures, and anyone who thinks games shouldn't require a couch.

The one rule WAYBOUND never breaks: every place you walk to is real. If the real-world discovery pipeline fails, the app says so. It never quietly substitutes a fictional location.

▶ Play WAYBOUND · ⭐ Star on GitHub

Demo

👉 Live app: https://waybound-frontend.onrender.com/

The full flow in five steps:

  1. Enable location — browser GPS or pick an exploration city
  2. Choose your adventure — pick an archetype (Mystery Seeker, Nature Lover, Fitness Scout…), duration (15 / 30 / 60 min), and difficulty
  3. Follow the map — a dark-themed Google Maps view shows mystery search zones, live GPS position, and walking routes to clue waypoints
  4. Solve clues — tap ? markers to read unlocked narrative riddles; voice narration is available hands-free via ElevenLabs or browser TTS
  5. Arrive & claim XP — server-side Haversine geofence verification confirms physical arrival; XP is awarded and persisted atomically

Code

GitHub logo itsdevcode / waybound

An open-source AI adventure companion that turns nearby places into personalized real-world quests, encouraging people to explore, walk, connect, and spend more time outdoors.

WAYBOUND — Turn Real Places Into Real Adventures

WAYBOUND

Turn Real Places Into Real Adventures.

An AI-powered real-world mystery adventure platform.

WAYBOUND transforms ordinary neighborhood walks and nearby public landmarks into immersive, game-like mystery expeditions. Powered by open-weights Gemma AI, Google Places discovery, live GPS geolocation, and walking route navigation, WAYBOUND encourages explorers to get outside, solve environmental clues, discover hidden secrets in their cities, and team up with friends.

Play WAYBOUND    View Source    Report Bug    Request Feature

GitHub Stars   GitHub Forks   Open Issues   PRs Welcome   MIT License

Python 3.12   FastAPI   Next.js   TypeScript   PostgreSQL   Google Maps Platform   Google Gemma 2   Tailwind CSS


🌟 Project Overview

WAYBOUND bridges the gap between outdoor fitness, real-world exploration, and tabletop role-playing games.

Unlike conventional navigation applications (such as Google Maps or Apple Maps) that simply give you the shortest route from Point A to Point B, WAYBOUND deliberately keeps your final destination a secret. Instead, it generates an unfolding mystery adventure around you:

  • 🔍 Real Locations, Never Fake Content: Every quest is grounded in authentic, publicly accessible parks, historical monuments, public art installations, architectural landmarks, or viewpoints queried via Google Places API…
View on GitHub

The full stack:

Layer Technology
Frontend Next.js 16 · React 19 · TypeScript · Tailwind CSS
Backend Python 3.12 · FastAPI · SQLAlchemy 2.0 (async) · PostgreSQL · Alembic
Location Discovery Google Places API (New) — real public places only
Maps & Navigation Google Maps JS SDK · Google Routes API (walking polylines + ETA)
AI Storytelling Google Gemma 2 (open-weights, via Google AI API)
Voice Narration ElevenLabs TTS · Browser Web Speech API fallback
Authentication Passwordless email OTP (HMAC-SHA256, Resend / SMTP / Gmail)
Deployment Render Blueprint (IaC, auto-migration, managed PostgreSQL)
Testing Pytest (133 backend cases) · Vitest (74 frontend cases)

How I Built It

The Core Architecture Problem: AI Lies About Places

AI is brilliant at generating vivid, convincing place descriptions. It will happily invent an "ancient clock tower on Merchant Street" with the confidence of a local historian — even if that tower doesn't exist.

In a couch game, that's harmless. In an app that asks people to physically walk somewhere, it's a fundamental failure of trust.

The entire WAYBOUND architecture is designed around one constraint:

Google Places finds the real location. AI writes the story around it. Never the other way around.

Here's the validated pipeline every quest passes through before it reaches a player:

User GPS Coordinates
        │
        ▼
Google Places API ──► Candidate Real Places
        │
        ▼
Gemma 2 AI Layer ──► Mission Title + Clues + Proposed Waypoints
        │
        ▼
Backend Validation ──► semantically_matches_clue()? is_publicly_accessible()?
        │
        ▼
Quest Stored in PostgreSQL (only validated, real Place IDs)
        │
        ▼
Frontend: Progressive Reveal ──► Player walks, unlocks clues, arrives
Enter fullscreen mode Exit fullscreen mode

The AI Storytelling Service

The GemmaQuestProvider receives:

  • The validated destination (a real place with a verified Google Place ID)
  • Up to two semantically matched intermediate waypoints
  • The explorer's approximate area and chosen archetype

From that, Gemma generates a mission narrative, escalating riddle clues, and an atmospheric story arc. The AI proposes waypoints by description; the backend runs two validation checks before any waypoint is ever stored:

# app/services/providers/gemma.py (simplified)
def is_publicly_accessible(candidate: PlaceCandidate) -> bool:
    """Rejects permanently/temporarily closed locations and inaccessible types."""
    if candidate.business_status in ("CLOSED_PERMANENTLY", "CLOSED_TEMPORARILY"):
        return False
    if candidate.primary_type in INACCESSIBLE_TYPES:
        return False
    return True

def semantically_matches_clue(clue: str, candidate: PlaceCandidate) -> bool:
    """
    Validates that a waypoint candidate semantically matches the clue text.
    Uses significant name tokens + a curated landmark synonym dictionary
    (e.g. 'fountain' → {'basin', 'water', 'cascade', 'pool', 'spout'}).
    """
    clue_lower = clue.lower()
    name_tokens = [t.lower() for t in re.findall(r"\b[A-Za-z0-9]{3,}\b", candidate.name)
                   if t.lower() not in STOP_WORDS]
    for token in name_tokens:
        if token in clue_lower:
            return True
        if any(syn in clue_lower for syn in LANDMARK_SYNONYMS.get(token, set())):
            return True
    return False
Enter fullscreen mode Exit fullscreen mode

If validation fails, the waypoint slot stays empty and the adventure continues without it — no invented fallback, ever.

Real-World Reward Engineering

Arrival verification can't just be a client-side check — GPS coordinates are trivially spoofable. WAYBOUND runs Haversine distance calculation server-side before awarding any XP. Quest completions are stored atomically with duplicate-prevention logic, so repeated requests for the same quest yield no additional reward.

Cooperative Party Mode

In two-player fellowship mode, the system distributes complementary clue fragments between partners. One explorer sees Fragment I (the where); the other sees Fragment II (the why). To progress, they have to communicate — turning walking with someone into solving something together.

Google Places Integration

The GooglePlacesService queries the Places API (New) searchNearby endpoint with a curated set of public exploration types (parks, museums, monuments, historical landmarks, sculptures, botanical gardens) and a strict field mask that avoids expensive billing fields. Results are cached in-memory with a 5-minute TTL to minimize API cost during repeated session loads.

Why Does Open Innovation Matter?

WAYBOUND is built around Google Gemma 2, an open-weight large language model. That choice was deliberate, not incidental — and it shapes what the project can and can't do.

Open weights let the architecture be honest about failure modes.

A closed API that hides its model weights and training data makes it extremely difficult to audit why it invents a place, how to constrain it, or how the model would behave across different geographies and languages. With Gemma's open-weight nature, the entire pipeline — from prompt construction to output validation — can be inspected, forked, and improved in public.

More concretely, open innovation made the following possible:

  1. Community-auditable anti-hallucination logic. The semantically_matches_clue() validator and the LANDMARK_SYNONYMS dictionary are open for anyone to extend. A contributor in Tokyo can add Japanese landmark synonym mappings. One in São Paulo can tune the validator for Portuguese place naming conventions. A closed model would make this sort of collaborative curation nearly impossible.

  2. Deployable without vendor lock-in. Because the model weights are open, a self-hosted deployment (e.g., via Ollama or a local inference server) is entirely feasible. No single API provider can unilaterally break WAYBOUND's core functionality by changing pricing or access terms.

  3. Trustworthy for outdoor navigation. People following WAYBOUND into unfamiliar areas need to trust the system. Open-source code means the full validation pipeline is auditable: the community can verify that no place is ever fabricated and that arrival verification happens server-side. That transparency is hard to achieve with a black-box platform.

  4. Extensible by the community. The provider architecture (QuestProvider base class → GemmaQuestProvider implementation) is designed so contributors can swap in alternative open-weight models without touching the quest generation orchestration layer. WAYBOUND can evolve alongside the open-source AI ecosystem.

Open innovation didn't just make WAYBOUND possible — it made it trustworthy in the specific way that a real-world application demands.

Prize Categories

  • Hacktoberfest Open-Source AI Challenge — Week 1: Touch Grass
  • Google AI / Gemma track (open-weights AI: Google Gemma 2)
  • Google Maps Platform track (Google Places API, Google Routes API, Google Maps JS SDK)

Your city. Your story. Your adventure.

Have a city in mind? Drop it in the comments — I'd love to hear what mystery you'd want to solve there.

Top comments (0)