bookibra/doc/backend-yapisi.md

Bookibra - Backend Dokümantasyonu

Backend Genel Bakış

Backend, Node.js ve Express.js kullanılarak geliştirilmiş REST API sunucusudur. Amazon kitap verilerini scraping eder, kullanıcı kimlik doğrulaması yönetir ve önbellekleme sağlar.

Teknoloji Yığını

Teknoloji	Versiyon	Kullanım Amacı
Express	^5.1.0	Web framework
Node.js	-	Runtime environment
PostgreSQL	8.16.3	Kullanıcı veritabanı
Redis (ioredis)	^5.8.2	Önbellekleme
Socket.IO	^4.8.1	WebSocket desteği
JWT	^9.0.2	Kimlik doğrulama
bcrypt	^6.0.0	Şifre hashleme
Axios	^1.13.2	HTTP istekleri
Cheerio	^1.1.2	HTML parsing

Dizin Yapısı

src/
├── config/
│   ├── env.js              # Ortam değişkenleri yapılandırması
│   ├── services.js         # Redis ve PostgreSQL bağlantıları
│   └── socket.js           # Socket.IO yapılandırması
├── controllers/
│   ├── authController.js   # Kimlik doğrulama endpoint'leri
│   └── bookController.js   # Kitap arama endpoint'leri
├── middleware/
│   ├── auth.js             # JWT doğrulama middleware
│   ├── errorHandler.js     # Hata yakalama middleware
│   ├── notFound.js         # 404 middleware
│   └── requestLogger.js    # İstek loglama middleware
├── routes/
│   ├── authRoutes.js       # /api/auth rotaları
│   └── bookRoutes.js       # /api/books rotaları
├── services/
│   ├── amazonService.js    # Amazon scraping iş mantığı
│   ├── cacheService.js     # Redis önbellekleme
│   └── userService.js      # Kullanıcı işlemleri
├── utils/
│   ├── isbn.js             # ISBN doğrulama ve normalizasyon
│   ├── logger.js           # Loglama yardımcıları
│   ├── mediaCache.js       # Medya önbellekleme
│   └── request.js          # İstek parametre çözümleme
├── validators/
│   └── authValidators.js   # İstek doğrulama kuralları
├── app.js                  # Express uygulaması
└── server.js               # HTTP sunucusu

API Endpoint'leri

Sağlık Kontrolü

GET /health

Cevap: {"status": "ok", "timestamp": "2026-02-10T..."}

Kitap Endpoint'leri

ISBN ile Arama

GET /api/books/isbn/:isbn

Query Parametreleri:

• locales (string): Amazon siteleri (örn: "tr,en" veya "tr")
• withGemini (boolean): Gemini AI entegrasyonu
• limit (number): Sonuç sayısı limiti

Örnek:

GET /api/books/isbn/9786053717355?locales=tr,en&withGemini=false&limit=3

Cevap:

{
  "isbn": "9786053717355",
  "normalizedIsbn": "9786053717355",
  "locales": ["tr", "en"],
  "includeGemini": false,
  "data": {
    "tr": {
      "title": "Suç ve Ceza",
      "authorName": "Fyodor Dostoyevski",
      "isbn": "9786053717355",
      "thumbImage": "https://...",
      "page": 752,
      "rate": 4.5,
      "publisher": "İthaki Yayınları"
    },
    "en": { ... }
  },
  "cacheHit": false,
  "cachedAt": "2026-02-10T..."
}

Başlık ile Arama

GET /api/books/title?title={kitap-adi}

Query Parametreleri:

• title (required): Kitap başlığı
• locales (optional): Amazon siteleri
• withGemini (optional): Gemini AI entegrasyonu
• limit (optional): Sonuç limiti (default: 3)

Örnek:

GET /api/books/title?title=Su%C3%A7%20ve%20Ceza&locales=tr&limit=5

Başlık ve Tarihe Göre Filtreleme

GET /api/books/filter?title={kitap-adi}&published={yil}

Query Parametreleri:

• title (required): Kitap başlığı
• published (required): Yayın yılı
• locales, withGemini, limit: ISBN aramasıyla aynı

Örnek:

GET /api/books/filter?title=Sapiens&published=2011&locales=en

Kimlik Doğrulama Endpoint'leri

Kayıt Olma

POST /api/auth/register

İstek Gövdesi:

{
  "email": "ornek@email.com",
  "password": "sifre123"
}

Cevap:

{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "user": {
    "id": "uuid",
    "email": "ornek@email.com"
  }
}

Giriş Yapma

POST /api/auth/login

İstek Gövdesi: Kayıt olma ile aynı

Cevap: Kayıt olma ile aynı

Profil Bilgisi

GET /api/auth/profile

Header: Authorization: Bearer {token}

Cevap:

{
  "user": {
    "id": "uuid",
    "email": "ornek@email.com"
  }
}

Middleware Yapısı

1. Auth Middleware (src/middleware/auth.js)

JWT token doğrulaması yapar.

// Kullanıcı
req.user = { id: decoded.sub, email: decoded.email }

2. Error Handler Middleware (src/middleware/errorHandler.js)

Hataları yakalar ve standart formatta döner.

// Cevap formatı
res.status(error.status || 500).json({
  message: error.message || 'Sunucu hatası'
})

3. Request Logger Middleware (src/middleware/requestLogger.js)

Her isteği loglar. Ortam değişkeni ile kontrol edilir:

• REQUEST_LOGGING=true → Aktif

4. Not Found Middleware (src/middleware/notFound.js)

Tanımsız rotalar için 404 döner.

Servis Katmanı

Amazon Service (src/services/amazonService.js)

Amazon'dan kitap verisi çekme iş mantığı.

Ana Fonksiyonlar:

• getBooksByIsbn(isbn, locales, includeGemini): ISBN ile arama
• searchBooksByTitle({ title, locales, includeGemini, limit }): Başlık ile arama
• searchBooksByTitleAndDate(...): Başlık ve tarih ile arama

Dış Bağımlılıklar:

• szbk-amazon-book-search: Amazon scraping kütüphanesi

Cache Service (src/services/cacheService.js)

Redis ile önbellekleme iş mantığı.

Cache Anahtar Formatları:

• ISBN: book:isbn:{isbn}:loc={tr,en}:gem={0|1}
• Title: book:title:q={title}:loc={...}:gem={...}:limit={n}
• Filter: book:filter:q={title}:pub={year}:loc={...}:gem={...}:limit={n}

Cache TTL: 6 saat (21600 saniye)

User Service (src/services/userService.js)

PostgreSQL ile kullanıcı işlemleri.

Veritabanı Tablosu:

CREATE TABLE users (
  id VARCHAR(36) PRIMARY KEY,
  email VARCHAR(255) UNIQUE NOT NULL,
  password_hash TEXT NOT NULL,
  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
);

Ana Fonksiyonlar:

• ensureUserTable(): Tablo oluşturma
• createUser({ email, password }): Yeni kullanıcı
• validateCredentials({ email, password }): Giriş doğrulama
• buildAuthResponse(user): Token ve kullanıcı bilgisi

Socket.IO Entegrasyonu

WebSocket bağlantıları için Socket.IO kullanılır.

Yapılandırma (src/config/socket.js):

// Bağlantı eventi
io.on('connection', (socket) => {
  socket.emit('connection:ack', {
    message: 'Bookibra soket servisine hos geldiniz.'
  });
});

Veritabanı Yapılandırması

PostgreSQL Bağlantısı

// src/config/services.js
const pgPool = new Pool({
  host: env.postgres.host,      // postgres
  port: env.postgres.port,      // 5432
  database: env.postgres.database, // bookibra
  user: env.postgres.user,      // bookibra
  password: env.postgres.password // bookibra
});

Redis Bağlantısı

const redis = new Redis(env.redisUrl, {
  lazyConnect: true,
  maxRetriesPerRequest: null
});

Ortam Değişkenleri

NODE_ENV=development
PORT=8080
GEMINI_API_KEY=your_gemini_key      # İsteğe bağlı
ALLOWED_ORIGINS=*                   # CORS için
REQUEST_LOGGING=true
REDIS_URL=redis://redis:6379
ISBN_CACHE_TTL_SECONDS=21600
JWT_SECRET=please_change_me         # Production'da değiştirilmeli
JWT_EXPIRES_IN=1h
POSTGRES_HOST=postgres
POSTGRES_PORT=5432
POSTGRES_DB=bookibra
POSTGRES_USER=bookibra
POSTGRES_PASSWORD=bookibra

Hata Yönetimi

Tüm hatalar errorHandler middleware tarafından yakalanır.

Hata Durum Kodları:

• 400: Geçersiz istek parametresi
• 401: Kimlik doğrulama hatası
• 404: Kaynak bulunamadı
• 409: Çakışma (örn: email zaten kayıtlı)
• 500: Sunucu hatası

Güvenlik

1. JWT: Kimlik doğrulama için JWT token kullanılır
2. bcrypt: Şifreler hash'lenir (10 rounds)
3. CORS: Çapraz kaynak istekleri kontrol edilir
4. Input Validation: express-validator ile istek doğrulama

---

İlgili Dosyalar:

• Proje Genel Bakış
• Frontend Yapısı
• Teknoloji Yığını