PusulAI — Otonom Seyahat Asistanı

Doğal dil ile otel & uçak arama, kart ödemeli rezervasyon ve AI destekli seyahat planlama

---

İçindekiler

• Proje Hakkında
• Ekran Görüntüleri
• Özellikler
• Mimari
• Tech Stack
• Kurulum
• Ortam Değişkenleri
• Chatbot Kuralları
• Testler
• Git Akışı
• Lisans

---

Proje Hakkında

PusulAI, SAN TSG & PAXIMUM Üniversite Staj Programı 2026 kapsamında geliştirilen, yapay zeka destekli bir seyahat asistanı uygulamasıdır.

Kullanıcılar doğal dilde seyahat taleplerini iletir — "25 Ağustos'ta Antalya'da 1 gece 1 yetişkin otel arıyorum" — chatbot eksik bilgileri soru-cevap ile tamamlar, TourVisio API üzerinden gerçek otel ve uçuş sonuçlarını listeler, kullanıcıyı kontrollü rezervasyon akışına yönlendirir ve Stripe ile kart ödemesini tamamlatır.

Proje adı neden PusulAI? Pusula, yolcuya yön gösterir. PusulAI de seyahat kararlarında kullanıcıya yön gösteren akıllı bir asistan olmayı hedefler.

Öne çıkanlar:

• 🧭 Tool-use tabanlı chatbot — AI, otel/uçuş aramayı ve rezervasyonu gerçek fonksiyon çağrılarıyla yürütür; fiyat/müsaitlik "uydurmaz".
• ✈️ Otel + uçak + seyahat paketi — tek sohbette otel ve uçuşu birlikte planlayıp tek rezervasyonda birleştirir.
• 💳 Uçtan uca rezervasyon — kullanıcı onaylı akış + Stripe test modunda kartla ödeme.
• 🔐 Kurumsal seviye kimlik — JWT, Google OAuth, e-posta doğrulama, şifre sıfırlama.
• 🛡️ Admin paneli & RBAC — metrikler, kullanıcı/rezervasyon yönetimi, token & denetim logları, destek talepleri.
• 🔄 6 AI sağlayıcı + failover — biri hata verirse sıradaki sağlayıcı otomatik devreye girer.

---

Ekran Görüntüleri

🤖 AI Sohbet + Otel Arama

Kullanıcı doğal dilde talep iletir, chatbot eksik bilgileri tamamlar ve TourVisio'dan gelen gerçek otelleri hem sohbet içinde hem sağ panelde kart olarak listeler.

✈️ Uçuş Arama

Aynı sohbette uçuş araması yapılır; kalkış/varış, saat ve fiyat bilgileriyle uçuşlar listelenir.

🧳 Rezervasyonlarım

Otel ve uçuş, tek bir seyahat paketi altında birleştirilir; tür, tarih ve duruma göre filtrelenir.

👑 Planlar

Free / Pro / Enterprise abonelik planları; her plan için AI mesaj kotası, favori/karşılaştırma limitleri ve ayrıcalıklar.

🛡️ Admin Paneli

Sistem metrikleri, rezervasyon hacmi, AI maliyeti, kullanıcı/rezervasyon yönetimi, token & denetim logları ve destek talepleri.

---

Özellikler

🤖 AI Sohbet Arayüzü

• Tool-use (fonksiyon çağırma) tabanlı sohbet — AI arama/rezervasyonu gerçek araçlarla yürütür
• Eksik parametreleri (tarih, kişi, gece, konum) soru-cevap ile tamamlama
• Konuşma geçmişi sidebar'da AI tarafından üretilen kısa başlıklarla listelenir
• Dosya ekleme (paperclip) ve sesli giriş (mikrofon / Web Speech API, tr-TR)
• Konu dışı mesajlara 3-uyarı kilit sistemi (moderasyon)
• Karanlık / aydınlık tema, TR/EN dil desteği (i18n)

🏨 Otel & ✈️ Uçak Arama

• Lokasyon, tarih, kişi sayısı, yıldız, pansiyon tipi ile filtreleme
• TourVisio API'den gerçek zamanlı otel ve uçuş sonuçları, sağ panelde kart görünümü
• Otel detay sayfası, medya galerisi, olanaklar ve müsaitlik kontrolü
• Uçuş detayları: havayolu, kalkış/varış, aktarma, bagaj, fiyat sınıfı (BASIC/FLEX)
• Karşılaştırma — birden fazla otel/uçuşu yan yana kıyaslama
• Favoriler — beğenilen otelleri kaydetme

🧳 Rezervasyon & Ödeme

• Kullanıcı onaylı, adım adım rezervasyon akışı
• Otel + uçuşu tek seyahat paketi olarak birleştirme
• Stripe ile kartla ödeme (test modu)
• Kayıtlı yolcu profilleri ile hızlı doldurma
• Tüm rezervasyonları listeleme, filtreleme ve detay ekranı
• Rezervasyon onayında PDF ekli e-posta bildirimi

🔐 Kimlik Doğrulama

• E-posta/şifre ile kayıt & giriş (JWT)
• E-posta doğrulama (6 haneli SMTP kodu)
• Google OAuth ile tek tıkla giriş (web yönlendirme + mobil ID token akışı)
• Şifre sıfırlama ve değiştirme (Google kullanıcıları için gizlenir)
• Refresh token desteği (mobil istemciler için)

👤 Profil & Planlar

• Profil yönetimi ve AWS S3 üzerinde avatar (private bucket, kısa ömürlü imzalı URL)
• Free / Pro / Enterprise abonelik planları ve kota yönetimi (plan-mode)
• Kota aşımında AI mesajı / karşılaştırma gibi işlemler kibarca kilitlenir

🛡️ Admin Paneli (RBAC)

• Rol tabanlı erişim: SuperAdmin / Support / ReadOnly
• Genel özet: toplam kullanıcı, rezervasyon hacmi, AI maliyeti, uptime
• Rezervasyon, kullanıcı, plan talebi ve ödeme yönetimi
• Token kullanım logları, denetim logları ve TourVisio hata logları
• Destek talepleri (support ticket) yönetimi

⚙️ Altyapı Özellikleri

• Redis ile cache-aside katmanı (otel detay, görsel, konum, arama sonuçları için ayarlanabilir TTL)
• 6 AI sağlayıcı arasında geçiş + failover (birincil hata verirse yedekler denenir)
• Sentry ile hata izleme/alerting (opsiyonel)
• Mobil API sözleşmesi — native istemciler için ayrı akışlar (docs/mobile)

---

Mimari

PusulAI
├── src/
│   ├── backend/                        # .NET 9 Clean Architecture
│   │   ├── src/
│   │   │   ├── PusulAI.Domain/         # Entity'ler, interface'ler, enum'lar
│   │   │   ├── PusulAI.Application/    # Use case'ler, servisler, DTO'lar, validasyon
│   │   │   ├── PusulAI.Infrastructure/ # TourVisio, AI, Stripe, S3, Email, Redis, EF Core
│   │   │   └── PusulAI.WebAPI/         # Controller'lar, middleware, DI
│   │   └── tests/
│   │       ├── PusulAI.Application.Tests/
│   │       └── PusulAI.IntegrationTests/
│   │
│   └── frontend/                       # React + TypeScript + Vite
│       └── src/
│           ├── components/             # chat, hotel, flight, compare, reservation, admin, landing…
│           ├── pages/                  # Chat, HotelDetail, Reservations, Profile, Landing, Admin…
│           ├── services/               # axios tabanlı API istemcileri
│           ├── contexts/               # Auth, Theme, LogoutConfirm context'leri
│           └── types/                  # TypeScript tip tanımları
│
├── docs/                               # API koleksiyonu, mimari, mobil rehber, ekran görüntüleri
├── docker-compose.yml                  # postgres + redis + backend + frontend
└── .env.example

Katman Sorumluluğu

Kullanıcı (Browser / Mobil)
      │
      ▼
 React Frontend
      │  REST /api
      ▼
 .NET WebAPI  ──────────────────────────────────────────────┐
      ├── Application Layer  →  ChatApplicationService, AuthService, ReservationService
      │       └── Fire-and-forget AI başlık üretimi (IServiceScopeFactory)
      ├── Domain Layer        →  ChatSession, Reservation, Subscription, User…
      └── Infrastructure
            ├── AI Providers  →  DeepSeek / Gemini / Claude / OpenAI / Groq / Ollama (+failover)
            ├── TourVisio     →  Otel & uçuş arama / rezervasyon
            ├── Payments      →  Stripe (kartla ödeme)
            ├── Email         →  SMTP (doğrulama + rezervasyon PDF)
            ├── Storage       →  AWS S3 (avatar)
            ├── Caching       →  Redis (cache-aside)
            └── EF Core       →  PostgreSQL 16

Güvenlik ilkesi: Browser hiçbir zaman doğrudan TourVisio, AI, Stripe veya S3'e istek atmaz. Tüm dış çağrılar backend üzerinden geçer; API key'ler yalnızca sunucuda tutulur.

---

Tech Stack

Backend

Teknoloji	Kullanım
.NET 9	Web API runtime
ASP.NET Core	HTTP pipeline, controller'lar, DI
Entity Framework Core 9	ORM, PostgreSQL
PostgreSQL 16	Ana veritabanı
Redis 7	Cache-aside katmanı
FluentValidation	Request doğrulama
Stripe.net	Kartla ödeme
AWS SDK (S3)	Avatar depolama
Sentry	Hata izleme (opsiyonel)
xUnit + Moq	Unit & entegrasyon testleri

Frontend

Teknoloji	Kullanım
React 18 + TypeScript 5	UI framework
Vite	Build tool
Tailwind CSS	Utility-first stil
Framer Motion	Animasyonlar
TanStack Query	Sunucu durumu / cache
Zustand	İstemci durumu
Axios	HTTP istemcisi
React Router 6	Sayfa yönlendirme
react-i18next	Çoklu dil (TR/EN)
Recharts	Admin grafik/metrikleri
React Leaflet	Otel harita görünümü
Stripe.js	Ödeme formu

AI Sağlayıcıları (değiştirilebilir)

Sağlayıcı	Durum	Tool-use
DeepSeek	Aktif (varsayılan)	✅
Google Gemini	Destekleniyor	✅
Groq	Destekleniyor	✅
Ollama (yerel)	Destekleniyor	✅
Anthropic Claude	Destekleniyor	⚠️ tool-use yok
OpenAI	Destekleniyor	⚠️ tool-use yok

Sağlayıcı AI__Provider ile seçilir. AI__FallbackProviders ile birincil hata verdiğinde denenecek yedekler tanımlanır. Tool-use gerektiren arama/rezervasyon akışları için Gemini/DeepSeek/Groq/Ollama önerilir.

---

Kurulum

🐳 Docker ile (Önerilen)

# 1. Repo'yu klonla
git clone https://github.com/mertosmanayhan/PusulAI.git
cd PusulAI

# 2. Ortam değişkenlerini ayarla
cp .env.example .env
# .env dosyasını düzenle (DB şifresi, JWT_SECRET_KEY, AI API key, TourVisio bilgileri)

# 3. Tüm servisleri başlat (postgres + redis + backend + frontend)
docker compose up --build

Servis	URL
Frontend	http://localhost:5173
Backend API	http://localhost:5000/api
API Docs (Scalar)	http://localhost:5000/scalar/v1
PostgreSQL	localhost:5432
Redis	localhost:6379

Portlar .env içinden değiştirilebilir (FRONTEND_PORT, BACKEND_PORT, POSTGRES_PORT, REDIS_PORT).

🔧 Manuel Kurulum

Gereksinimler: .NET 9 SDK · Node.js 20+ · PostgreSQL 16 · Redis 7

# Backend
cd src/backend/src/PusulAI.WebAPI
cp appsettings.example.json appsettings.Development.json
# appsettings.Development.json içini doldur
dotnet restore
dotnet ef database update
dotnet run

# Frontend (ayrı terminalde)
cd src/frontend
cp .env.example .env          # VITE_API_BASE_URL=http://localhost:5000/api
npm install
npm run dev

---

Ortam Değişkenleri

.env dosyası (kök dizin, Docker için). Tam liste ve açıklamalar için .env.example dosyasına bakın.

# --- Zorunlu ---
DB_PASSWORD=changeme
JWT_SECRET_KEY=<openssl rand -base64 48 ile üretin, min 32 karakter>

# --- AI (gemini | claude | openai | groq | deepseek | ollama) ---
AI__Provider=DeepSeek
AI__FallbackProviders=            # örn: DeepSeek,Groq (boş = failover kapalı)
AI__DeepSeek__ApiKey=sk-...
AI__DeepSeek__Model=deepseek-v4-flash

# --- TourVisio (sunucu tarafında kalır) ---
TOURVISIO_BASE_URL=https://tourvisio-api-url
TOURVISIO_AGENCY=your_agency_code
TOURVISIO_USERNAME=your_username
TOURVISIO_PASSWORD=your_password

# --- Opsiyonel entegrasyonlar (boş bırakılırsa ilgili özellik devre dışı kalır) ---
GOOGLE_CLIENT_ID=                 # Google OAuth
GOOGLE_CLIENT_SECRET=
SMTP_HOST=smtp.gmail.com          # E-posta doğrulama (boşsa kod log'a yazılır)
SMTP_USERNAME=
SMTP_PASSWORD=
STRIPE_SECRET_KEY=                # Kartla ödeme (test modu)
STRIPE_PUBLISHABLE_KEY=
AWS_S3_BUCKET_NAME=               # Avatar depolama (private bucket)
SENTRY_DSN=                       # Hata izleme

Güvenlik: .env ve appsettings.Development.json dosyaları .gitignore'a eklenmiştir ve kesinlikle commit edilmemelidir. Tüm opsiyonel entegrasyonlar boş bırakıldığında uygulamanın geri kalanı çalışmaya devam eder — ilgili özellik anlamlı bir hata döndürerek devre dışı kalır.

---

Chatbot Kuralları

Chatbot yapabilir:

• Kullanıcının otel / uçak arama niyetini anlamak
• Eksik parametreleri soru-cevap ile tamamlamak
• TourVisio'dan gelen sonuçları listelemek ve filtrelemek
• Otel ve uçuşu birlikte seyahat paketi olarak değerlendirmek
• Kullanıcıyı rezervasyon ve ödeme ekranına yönlendirmek

Chatbot yapamaz:

• Kullanıcı onayı olmadan rezervasyon veya ödeme tamamlamak
• API'den gelmeyen fiyat veya müsaitlik üretmek ("hallucinate")
• API key, sistem prompt veya teknik gizli bilgi paylaşmak
• Seyahat dışı konulara cevap vermek (3 ihlalde oturum kilitlenir)

---

Testler

cd src/backend
dotnet test

İki test projesi bulunur:

• PusulAI.Application.Tests — servis ve iş kuralı unit testleri
  • ChatApplicationServiceTests — oturum oluşturma, mesaj gönderme
  • ChatApplicationServiceModerationTests — konu dışı mesaj / kilit akışı
  • Rezervasyon, plan/kota, ödeme ve doğrulama testleri
• PusulAI.IntegrationTests — API uçtan uca / entegrasyon testleri

# Frontend testleri
cd src/frontend
npm run test    # Vitest

---

Git Akışı

main          ←── production-ready, korumalı
  └── develop ←── aktif geliştirme
        ├── feature/landing-page
        ├── feature/reservation-payment-integration
        ├── feature/enterprise-email-templates
        ├── feature/plan-mode
        └── fix/...

• Her yeni özellik için develop'tan branch açılır
• PR açılmadan develop'a merge yapılmaz
• Commit mesajları feat:, fix:, docs:, refactor:, chore: önekleriyle yazılır

---

Lisans

Bu proje SAN TSG & PAXIMUM Üniversite Staj Programı 2026 kapsamında eğitim amaçlı geliştirilmiştir.

---

_{SAN Tourism Software Group  |  2026}