bookibra/README.md

Bookibra 📚

Bookibra, Amazon'dan kitap verilerini çeken, barkod tarama özelliği olan ve kişisel kitap kütüphanesi yönetimi sağlayan modern bir full-stack web uygulamasıdır.

📋 Proje Hakkında

Bookibra, kitap severler için geliştirilmiş bir platformdur. Ana özellikleri:

• 🔍 Kitap Arama: ISBN veya başlık ile kitap arama
• 📸 Barkod Tarama: Kamera ile ISBN barkod tarama
• 🌍 Çoklu Dil: Türkçe ve İngilizce Amazon sitelerinden veri çekme
• 💾 Kütüphane Yönetimi: Kitapları kaydetme ve organize etme
• ⚡ Önbellekleme: Redis ile hızlı erişim

🏗️ Mimari

┌─────────────┐      ┌─────────────┐      ┌─────────────┐
│  Frontend   │─────▶│   Backend   │─────▶│  Amazon     │
│  (React)    │      │  (Express)  │      │  Scraping   │
└─────────────┘      └─────────────┘      └─────────────┘
                            │
        ┌───────────────────┼───────────────────┐
        ▼                   ▼                   ▼
┌─────────────┐      ┌─────────────┐      ┌─────────────┐
│   Redis     │      │ PostgreSQL  │      │  Socket.IO  │
│  (Cache)    │      │  (Users)    │      │ (WebSocket) │
└─────────────┘      └─────────────┘      └─────────────┘

🚀 Hızlı Başlangıç

Gereksinimler

• Docker ve Docker Compose
• Node.js 20+ (Docker olmadan geliştirme için)

Docker ile Başlatma

1. Projeyi klonlayın:

git clone https://github.com/yourusername/bookibra.git
cd bookibra

2. Ortam değişkenlerini yapılandırın:

cp .env.example .env
# .env dosyasını düzenleyin (JWT_SECRET vb.)

3. Tüm servisleri başlatın:

docker-compose up --build

4. Tarayıcıda açın:

• Frontend: http://localhost:5173
• Backend API: http://localhost:8080
• Health Check: http://localhost:8080/health

Manuel Kurulum (Development)

Backend

# Backend dizininde
npm install
npm run dev

Frontend

# Frontend dizininde
npm install
npm run dev

📁 Proje Yapısı

bookibra/
├── doc/                    # Dokümantasyon
├── frontend/               # React Frontend
│   ├── src/
│   │   ├── components/     # React bileşenleri
│   │   ├── pages/          # Sayfalar
│   │   ├── context/        # Context API
│   │   └── main.jsx        # Giriş noktası
│   └── package.json
├── src/                    # Backend
│   ├── config/             # Yapılandırma
│   ├── controllers/        # Endpoint kontrolcüleri
│   ├── middleware/         # Express middleware
│   ├── routes/             # API rotaları
│   ├── services/           # İş mantığı
│   └── utils/              # Yardımcı fonksiyonlar
├── docker-compose.yml      # Docker orchestration
├── Dockerfile              # Backend Docker image
└── package.json

🔧 Ortam Değişkenleri

# Backend (.env)
NODE_ENV=development
PORT=8080
GEMINI_API_KEY=your_gemini_key      # İsteğe bağlı
ALLOWED_ORIGINS=*
REQUEST_LOGGING=true
REDIS_URL=redis://redis:6379
ISBN_CACHE_TTL_SECONDS=21600
JWT_SECRET=please_change_me         # Production'da değiştirin!
JWT_EXPIRES_IN=1h

# PostgreSQL
POSTGRES_HOST=postgres
POSTGRES_PORT=5432
POSTGRES_DB=bookibra
POSTGRES_USER=bookibra
POSTGRES_PASSWORD=bookibra

# Frontend (frontend/.env)
VITE_API_BASE_URL=http://localhost:8080

📡 API Endpoint'leri

Kitap Arama

Endpoint	Method	Açıklama
/api/books/isbn/:isbn	GET	ISBN ile kitap arama
/api/books/title	GET	Başlık ile kitap arama
/api/books/filter	GET	Başlık ve yıl ile filtreleme

Örnek:

# ISBN ile arama
curl "http://localhost:8080/api/books/isbn/9786053717355?locales=tr,en"

# Başlık ile arama
curl "http://localhost:8080/api/books/title?title=Suç%20ve%20Ceza&locales=tr"

# Tarih filtreleme
curl "http://localhost:8080/api/books/filter?title=Sapiens&published=2011"

Kimlik Doğrulama

Endpoint	Method	Açıklama
/api/auth/register	POST	Kayıt olma
/api/auth/login	POST	Giriş yapma
/api/auth/profile	GET	Profil bilgisi (Auth required)

Örnek:

# Kayıt olma
curl -X POST http://localhost:8080/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email":"user@example.com","password":"password123"}'

# Giriş yapma
curl -X POST http://localhost:8080/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"user@example.com","password":"password123"}'

🎨 Kullanım

Kitap Arama

1. Add Books sayfasına gidin
2. Arama kutusuna kitap adını yazın
3. Ara butonuna tıklayın
4. Sonuçları görüntüleyin ve kütüphanenize ekleyin

Barkod Tarama

1. Add Books sayfasında barkod ikonuna tıklayın
2. Kitabın barkodunu kameraya gösterin
3. Kitap bilgileri otomatik getirilecek

Kütüphane Yönetimi

1. My Books sayfasına gidin
2. Kayıtlı kitaplarınızı görüntüleyin
3. Detayları görmek için kitaba tıklayın
4. Silmek için "Remove from My Books" butonuna tıklayın

🛠️ Geliştirme

Backend Development

npm run dev    # nodemon ile development server
npm start      # Production server

Frontend Development

npm run dev    # Vite development server
npm run build  # Production build
npm run preview  # Build preview

Docker Development

# Tüm servisleri başlat
docker-compose up

# Arka planda çalıştır
docker-compose up -d

# Logları görüntüle
docker-compose logs -f

# Servisleri durdur
docker-compose down

# Volumes ile birlikte temizle
docker-compose down -v

📚 Dokümantasyon

Detaylı dokümantasyon için /doc dizinine bakın:

• Proje Genel Bakış - Proje hakkında genel bilgi
• Backend Yapısı - Backend detayları
• Frontend Yapısı - Frontend detayları
• Teknoloji Yığını - Kullanılan teknolojiler

🔐 Güvenlik

• JWT token tabanlı kimlik doğrulama
• bcrypt ile şifre hashleme (10 rounds)
• CORS yapılandırması
• Input validation (express-validator)

Production için:

• JWT_SECRET ortam değişkenini güçlü bir değerle değiştirin
• HTTPS kullanın
• Rate limiting ekleyin
• Güvenlik header'larını ekleyin (helmet)

🐛 Sorun Giderme

Redis Bağlantı Hatası

# Redis container'ının çalıştığından emin olun
docker-compose ps redis

# Redis loglarını kontrol edin
docker-compose logs redis

PostgreSQL Bağlantı Hatası

# PostgreSQL container'ını kontrol edin
docker-compose ps postgres

# Database'i yeniden oluşturun
docker-compose down -v
docker-compose up

Frontend API Erişim Hatası

# frontend/.env dosyasında VITE_API_BASE_URL'in doğru olduğundan emin olun
# Docker kullanıyorsanız: http://localhost:8080

📝 Lisans

ISC

🤝 Katkıda Bulunma

Katkılarınızı bekliyoruz! Lütfen:

1. Fork yapın
2. Feature branch oluşturun (git checkout -b feature/amazing-feature)
3. Değişikliklerinizi commit edin (git commit -m 'feat: Add amazing feature')
4. Branch'inizi push edin (git push origin feature/amazing-feature)
5. Pull Request açın

👥 Geliştiriciler

• Bookibra Development Team

---

Not: Bu proje AI agent'ların projeyi daha iyi anlaması için detaylı dokümantasyon ile geliştirilmiştir. Dokümantasyon /doc dizininde Türkçe olarak bulunabilir.