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:
```bash
git clone https://github.com/yourusername/bookibra.git
cd bookibra
```

2. Ortam değişkenlerini yapılandırın:
```bash
cp .env.example .env
# .env dosyasını düzenleyin (JWT_SECRET vb.)
```

3. Tüm servisleri başlatın:
```bash
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

```bash
# Backend dizininde
npm install
npm run dev
```

#### Frontend

```bash
# 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

```bash
# 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:**
```bash
# 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:**
```bash
# 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

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

### Frontend Development

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

### Docker Development

```bash
# 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ış](./doc/proje-genel-bakis.md) - Proje hakkında genel bilgi
- [Backend Yapısı](./doc/backend-yapisi.md) - Backend detayları
- [Frontend Yapısı](./doc/frontend-yapisi.md) - Frontend detayları
- [Teknoloji Yığını](./doc/teknoloji-yigini.md) - 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ı
```bash
# 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ı
```bash
# 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ı
```bash
# 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.