Fures Travel AI Companion

Bölüm 1: Bu Uygulama Nedir ve Ne İşe Yarar?

Kullanıcı gözünden baktığımızda Fures Travel, elinizin altında yaşayan bir gezi planlayıcısıdır. Sesinizle veya yazıyla konuştuğunuzda Gemini, Google Maps'in güncel verileriyle desteklenen öneriler üretir ve önerdiği yerleri Photorealistic 3D haritada işaretleyerek sizi sanal bir şehir turuna çıkarır.

Sesli ve yazılı etkileşim: Mikrofon açtığınız anda çift yönlü ses akışı başlar; dilerseniz metin tabanlı sohbeti tercih edebilirsiniz.
Anlık gezi planlama: “Gazimağusa'da öğlen yemeği yiyelim, ardından tarihi bir yer görelim” gibi doğal cümleler anında gündelik bir rota hâline gelir.
3D harita koreografisi: Anlatılan mekânlar haritada işaretlenir, kamera o noktaları çerçeveleyecek şekilde otomatik olarak ayarlanır.
Canlı veri entegrasyonu: Restoran popülerliği, müze teması veya çalışma saatleri gibi bilgiler Google Maps Places veritabanından çekilerek güncel biçimde sunulur.

Bu demo, yapay zekânın sadece metin üretmekle kalmayıp, harici servislerle konuşarak zengin ve görsel deneyimler yaratabileceğinin güçlü bir kanıtıdır.

Bölüm 2: Teknik Derinlemesine İnceleme

A. Temel Teknolojiler

Frontend

React + TypeScript ile geliştirilmiş tek sayfa uygulaması.

Yapay Zekâ

Gerçek zamanlı ses ve metin akışı sağlayan Google Gemini Live API.

Harita

Google Maps Photorealistic 3D Maps, Places API ve Geocoding API.

Durum Yönetimi

Zustand ile global sohbet geçmişi, marker listesi ve ayarların takibi.

B. Mimari Katmanlar

App.tsx: Sidebar, ControlTray, StreamingConsole ve Map3D bileşenlerini orkestre eder; Zustand store'u dinleyerek kamerayı günceller.
/components: Kontrol tepsisi, konuşma konsolu, 3D harita sarmalayıcısı ve pop-up gibi görsel elemanlar.
/hooks/use-live-api.ts: Gemini Live bağlantısını yöneten kalp atışı; ses göndermeyi, transkriptleri ve tool call'ları yönetir.
/lib: GenAILiveClient sarmalayıcısı, audio streamer, map controller ve tool registry gibi altyapı yardımcıları.
/contexts/LiveAPIContext: Hook'tan dönen bağlantı durumunu uygulama geneline taşır.

C. Veri Akışı

Kullanıcı, ControlTray üzerinden oturumu başlatır; use-live-api hook'u Gemini Live'a bağlanır.
Mikrofon verisi PCM formatına çevrilip anlık olarak gönderilir; yazılı mesajlar sendRealtimeText ile iletilir.
Gemini'den gelen ses veri paketleri AudioStreamer tarafından çalınır; metin transkriptleri StreamingConsole'da gösterilir.
Model bir araç çağırdığında (ör. mapsGrounding), tool-registry fonksiyonları devreye girer ve Google Maps'ten detayları çeker.
Zustand store güncellenir, MapController marker'ları ve kamerayı yeni verilere göre yeniden çerçeveler.
Sonuç modeli besler ve kullanıcıya doğal bir yanıt olarak geri döner.

Bölüm 3: Geliştirme ve Dağıtım

Başlangıç Adımları

Vite + React + TypeScript şablonuyla projeyi başlatın, @google/genai, @vis.gl/react-google-maps ve zustand paketlerini ekleyin.
Statik UI'ı kurun; ControlTray, StreamingConsole ve Map3D bileşenlerini tasarlayın.
Zustand store'larını (UI, sohbet geçmişi, harita) tanımlayın ve App.tsx içinde dinleyin.
Gemini Live entegrasyonu için GenAILiveClient ve use-live-api hook'unu hazırlayın; önce echo bot ile bağlantıyı doğrulayın.
Tool registry'yi oluşturup mapsGrounding, frameLocations gibi fonksiyonları uygulayın; harita state'ini güncelleyin.

Dağıtım Planı (GitHub + Netlify)

Projeyi GitHub deposuna gönderin ve Netlify'da yeni bir site olarak içeri aktarın.
Netlify build ayarlarında komut olarak npm run build kullanın; bu işlem hem ana siteyi hem travel demosunu paketler.
Environment Variables: Netlify ayarlarında GEMINI_API_KEY ve MAPS_API_KEY değerlerini tanımlayın.
Dağıtım tamamlandığında Netlify, /travel altında Vite çıktısını sunar ve public/projeler/travel sayfası projeyi detaylı biçimde anlatır.

API anahtarlarını tarayıcı tarafında kullanırken alan kısıtlamaları ve kota yönetimini unutmayın; Gemini için proxy veya token aracı eklemek isteyebilirsiniz.