Our app is live on vercel: maptourai

This project was initially developed under the name Locify and is now referred to as maptourai. File paths and source code may still use locify; both names describe the same application. maptourai provides real-time, proximity-based historical storytelling layered onto an interactive map.

Developers Discord Handle: @wwsoup, @nursultansagyntay, @shahzaib4248, and @hailemariam_16209

• Interactive map with Mapbox GL JS (standard, satellite, navigation styles)
• Global location search and map recentering
• Live user location tracking (custom arrow marker with accuracy visualization)
• Points of Interest (POIs) fetched once per session and cached client-side
• Proximity detection (e.g., within 50m) triggering narration display
• AI narration pipeline (backend: discovery + narration generation) ready for text-to-speech
• Planned extensions: avatar narration, multilingual output, voice synthesis, offline caching

The backend (deployed separately) exposes endpoint of interest (POI)nts consumed by the Next.js API routes (/api/places and /api/narration). Those proxy calls allow environment isolation and optional server-side caching.

• Node.js 18+ and npm
• Mapbox account and access token (Get one here)

1. Clone the repository:

git clone <your-repo-url>
cd locify/locify

2. Install dependencies:

npm install

3. Create a .env.local file in the locify/ directory:

NEXT_PUBLIC_MAPBOX_TOKEN=your_mapbox_token_here

4. Run the development server:

npm run dev

5. Open http://localhost:3000 in your browser

Create locify/.env.local with at least:

NEXT_PUBLIC_MAPBOX_TOKEN=your_mapbox_token_here

# Optional / planned
BACKEND_BASE_URL=https://locify-backend.onrender.com
NEXT_PUBLIC_ELEVENLABS_API_KEY=your_elevenlabs_api_key_here
NEXT_PUBLIC_DID_API_KEY=your_did_api_key_here
NEXT_PUBLIC_GEMINI_API_KEY=your_gemini_api_key_here

The frontend does not directly embed secret model keys for OpenAI/Anthropic; those remain backend-side.

locify/
├── app/                    # Next.js app directory
│   ├── layout.tsx         # Root layout
│   ├── page.tsx           # Main map page
│   └── globals.css        # Global styles
├── components/
│   ├── map/               # Map-related components
│   │   ├── map-controls.tsx
│   │   ├── map-search.tsx
│   │   └── map-styles.tsx
│   └── ui/                # shadcn/ui components
├── context/
│   └── map-context.ts     # Map context for state management
├── lib/
│   ├── mapbox/
│   │   └── provider.tsx   # Map provider component
│   └── utils.ts           # Utility functions
└── public/                # Static assets

1. User initiates tracking (or first location fix occurs).
2. Frontend calls /api/places (Next.js route) once → proxies to backend discovery → caches POIs in React context.
3. User movement updates distance calculations client-side (no extra discovery requests).
4. When distance < threshold (e.g., 50m), narration overlay fetches or reuses location narration.
5. (Planned) Narration text is transformed to synthesized voice and/or avatar performance.

• Single discovery request per session (or per new city region) limits external API usage.
• Distance calculations use haversine formula on the client (fast for small arrays of POIs).
• Narration fetches are cached per POI to avoid repeated network calls.

• TypeScript strictness enforced in hooks and API routes.
• Context provides a single source of truth for POIs and narration state.
• Avoid expensive re-renders: POIs stored once; distances derived.

npm run build
npm start

MIT

Pull requests are welcome. Please include:

• Clear description of change and rationale
• Tests or manual verification steps (where practical)
• Updates to README if you alter public behavior

MIT

The codebase root and many imports use locify. The official product name going forward is maptourai. Both refer to the same system; future refactors may consolidate naming for clarity.