docs: proje dokümantasyonunu ekle

README.md ve detaylı teknik dokümantasyon dosyaları (genel bakış, backend yapısı, frontend yapısı, teknoloji yığını) eklendi.
2026-02-10 21:57:56 +03:00
parent 6392533387
commit 836d60da78
5 changed files with 1334 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,299 @@
+# 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.
--- a/doc/backend-yapisi.md
+++ b/doc/backend-yapisi.md
@@ -0,0 +1,351 @@
+# 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:**
+```json
+{
+  "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:**
+```json
+{
+  "email": "ornek@email.com",
+  "password": "sifre123"
+}
+```
+
+**Cevap:**
+```json
+{
+  "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:**
+```json
+{
+  "user": {
+    "id": "uuid",
+    "email": "ornek@email.com"
+  }
+}
+```
+
+## Middleware Yapısı
+
+### 1. Auth Middleware (`src/middleware/auth.js`)
+
+JWT token doğrulaması yapar.
+
+```javascript
+// 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.
+
+```javascript
+// 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:**
+```sql
+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`):**
+```javascript
+// 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ı
+
+```javascript
+// 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ı
+
+```javascript
+const redis = new Redis(env.redisUrl, {
+  lazyConnect: true,
+  maxRetriesPerRequest: null
+});
+```
+
+## Ortam Değişkenleri
+
+```bash
+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ış](./proje-genel-bakis.md)
+- [Frontend Yapısı](./frontend-yapisi.md)
+- [Teknoloji Yığını](./teknoloji-yigini.md)
--- a/doc/frontend-yapisi.md
+++ b/doc/frontend-yapisi.md
@@ -0,0 +1,341 @@
+# Bookibra - Frontend Dokümantasyonu
+
+## Frontend Genel Bakış
+
+Frontend, **React 19** ve **Vite** kullanılarak geliştirilmiş modern bir SPA (Single Page Application) uygulamasıdır. Mobil öncelikli tasarıma sahiptir ve kitap arama, barkod tarama, kütüphane yönetimi özellikleri sunar.
+
+## Teknoloji Yığını
+
+| Teknoloji | Versiyon | Kullanım Amacı |
+|-----------|----------|----------------|
+| React | ^19.1.1 | UI framework |
+| Vite | ^7.1.7 | Build tool ve dev server |
+| React Router | ^7.9.5 | Client-side routing |
+| Framer Motion | ^12.23.24 | Animasyonlar |
+| FontAwesome | ^7.1.0 | İkonlar |
+| react-qr-barcode-scanner | ^2.1.18 | Barkod tarama |
+| react-image-glow | ^1.0.6 | Resim efektleri |
+| color-thief-react | ^2.1.0 | Renk extract |
+
+## Dizin Yapısı
+
+```
+frontend/src/
+├── components/           # Yeniden kullanılabilir bileşenler
+│   ├── BookCard.jsx      # Kitap kartı bileşeni
+│   └── SocialButton.jsx  # Sosyal medya butonu
+├── pages/                # Sayfa bileşenleri
+│   ├── HomePage.jsx      # Ana sayfa
+│   ├── MyBooksPage.jsx   # Kütüphane sayfası
+│   ├── AddBooksPage.jsx  # Kitap ekleme sayfası
+│   └── ProfilePage.jsx   # Profil sayfası
+├── context/              # React Context
+│   └── SavedBooksContext.jsx  # Kitap kütüphanesi state yönetimi
+├── assets/               # Statik dosyalar
+│   ├── booklibra-logo.svg
+│   └── ...
+├── App.jsx               # Ana uygulama bileşeni
+├── main.jsx              # Uygulama giriş noktası
+├── App.css               # Ana stiller
+└── index.css             # Global stiller
+```
+
+## Uygulama Mimarisi
+
+### App Bileşeni (`src/App.jsx`)
+
+Uygulamanın kök bileşenidir. Routing ve layout yapısını belirler.
+
+**Ana Özellikler:**
+- `SavedBooksProvider` ile context provider wrapping
+- `BrowserRouter` ile routing
+- Bottom navigation ile sayfa geçişi
+
+**Navigasyon Yapısı:**
+```javascript
+const tabs = [
+  { path: '/', label: 'Home', icon: faHouse },
+  { path: '/my-books', label: 'My Books', icon: faBookOpen },
+  { path: '/add-books', label: 'Add Books', icon: faPlusCircle },
+  { path: '/profile', label: 'Profile', icon: faUser }
+];
+```
+
+### Sayfalar
+
+#### 1. HomePage (`src/pages/HomePage.jsx`)
+
+Ana sayfa bileşeni. Şu anda basit bir başlık gösterir.
+
+**Gelecek Özellikler:**
+- Son eklenen kitaplar
+- Önerilen kitaplar
+- İstatistikler
+
+#### 2. AddBooksPage (`src/pages/AddBooksPage.jsx`)
+
+Kitap arama ve ekleme sayfası. En karmaşık sayfa bileşenidir.
+
+**Ana Özellikler:**
+- Başlık ile arama (yayın yılı filtreleme desteği)
+- Barkod tarama ile ISBN ile arama
+- Sonuçları listeleme
+- Kitapları kütüphaneye ekleme
+
+**Önemli Fonksiyonlar:**
+
+```javascript
+// API Base URL çözümleme
+const resolveApiBaseUrl = () => {
+  // 1. Environment variable kontrolü
+  // 2. Window location tabanlı çözümleme
+  // 3. Default localhost:8080
+};
+
+// Arama input'u parsing
+const parseSearchInput = (raw) => {
+  // "Kitap Adı .2020" → { title: "Kitap Adı", published: "2020" }
+  // "Kitap Adı" → { title: "Kitap Adı", published: undefined }
+};
+
+// API cevabını normalizasyon
+const normalizeBook = (item) => ({
+  title, authorName, thumbImage, page, rate,
+  publisher, description, isbn, raw
+});
+```
+
+**Barkod Tarama Akışı:**
+1. Kamera butonuna tıklama
+2. `react-qr-barcode-scanner` ile kamera açma
+3. Barkod algılama (`handleBarcodeUpdate`)
+4. ISBN ile API çağrısı
+5. Sonuçları gösterme
+
+**API Endpoint'ler:**
+- `/api/books/title?title={query}`
+- `/api/books/filter?title={query}&published={year}`
+- `/api/books/isbn/{isbn}?locales=en`
+
+#### 3. MyBooksPage (`src/pages/MyBooksPage.jsx`)
+
+Kullanıcının kayıtlı kitaplarını gösterir.
+
+**Ana Özellikler:**
+- Kitap listesi görünümü
+- Kitap detay görünümü
+- Kitap silme
+- Görsel efektler (ImageGlow)
+
+**State Yönetimi:**
+```javascript
+const { savedBooks, removeBook } = useSavedBooks();
+const [selected, setSelected] = useState(null);
+```
+
+**Detay Görünümü:**
+Seçili kitap için:
+- Kapak resmi (glow efekti ile)
+- Kitap bilgileri (başlık, yazar, sayfa, puan)
+- Açıklama
+- Silme butonu
+
+#### 4. ProfilePage (`src/pages/ProfilePage.jsx`)
+
+Kullanıcı profili sayfası. Şu anda placeholder durumunda.
+
+**Gelecek Özellikler:**
+- Kullanıcı bilgileri
+- Ayarlar
+- İstatistikler
+
+### Bileşenler
+
+#### BookCard (`src/components/BookCard.jsx`)
+
+Tek bir kitabı gösteren kart bileşeni.
+
+**Props:**
+```javascript
+{
+  book: {
+    title: string,
+    authorName: string,
+    thumbImage: string,
+    page: number,
+    rate: number,
+    ...
+  },
+  onSelect: (book) => void
+}
+```
+
+**Özellikler:**
+- Kitap kapak resmi
+- Başlık ve yazar
+- Sayfa sayısı ve puan
+- Tıklanabilir (onSelect callback)
+
+#### SocialButton (`src/components/SocialButton.jsx`)
+
+Sosyal medya giriş butonu.
+
+**Props:**
+```javascript
+{
+  provider: 'apple' | 'google',
+  onClick: () => void
+}
+```
+
+### Context Yönetimi
+
+#### SavedBooksContext (`src/context/SavedBooksContext.jsx`)
+
+Kitap kütüphanesi için global state yönetimi.
+
+**API:**
+```javascript
+const { savedBooks, addBook, removeBook } = useSavedBooks();
+```
+
+**Özellikler:**
+- `savedBooks`: Kayıtlı kitaplar dizisi
+- `addBook(book)`: Kitap ekleme (tekrarı kontrol eder)
+- `removeBook(title)`: Kitap silme
+
+**Persistence:**
+Kitaplar `localStorage`'da saklanır:
+```javascript
+localStorage.setItem('bookibra_saved_books', JSON.stringify(savedBooks));
+```
+
+## Stil Yapısı
+
+### Ana Layout (`App.css`)
+
+**Mobile Shell Pattern:**
+```css
+.mobile-shell {
+  display: flex;
+  flex-direction: column;
+  height: 100vh;
+}
+
+.page-container {
+  flex: 1;
+  overflow-y: auto;
+  padding-bottom: 70px; /* Bottom nav için boşluk */
+}
+```
+
+**Bottom Navigation:**
+```css
+.bottom-nav {
+  position: fixed;
+  bottom: 0;
+  width: 100%;
+  display: flex;
+  justify-content: space-around;
+}
+```
+
+### Renk Paleti
+
+CSS değişkenleri ile tanımlı:
+```css
+:root {
+  --primary: /* Ana renk */;
+  --secondary: /* İkincil renk */;
+  --accent: /* Vurgu rengi */;
+  --text: /* Metin rengi */;
+  --bg: /* Arka plan */;
+}
+```
+
+## API Entegrasyonu
+
+### API Base URL Çözümleme
+
+```javascript
+const resolveApiBaseUrl = () => {
+  // 1. Environment variable (VITE_API_BASE_URL)
+  if (import.meta.env.VITE_API_BASE_URL)
+    return import.meta.env.VITE_API_BASE_URL;
+
+  // 2. Window location (production)
+  if (typeof window !== 'undefined') {
+    const { protocol, hostname } = window.location;
+    return `${protocol}//${hostname}:8080`;
+  }
+
+  // 3. Default (development)
+  return 'http://localhost:8080';
+};
+```
+
+### Örnek API Çağrısı
+
+```javascript
+const response = await fetch(`${API_BASE_URL}/api/books/isbn/${isbn}?locales=en`);
+const data = await response.json();
+if (!response.ok) {
+  throw new Error(data.message || 'Kitap bulunamadi');
+}
+```
+
+## Build ve Deployment
+
+### Development
+
+```bash
+cd frontend
+npm install
+npm run dev
+```
+
+### Production Build
+
+```bash
+npm run build
+# Çıktı: dist/ dizini
+```
+
+### Docker Build
+
+```dockerfile
+FROM node:20-alpine
+WORKDIR /app
+COPY package*.json ./
+RUN npm install
+COPY . .
+RUN npm run build
+CMD ["npm", "run", "preview"]
+```
+
+## Ortam Değişkenleri
+
+```bash
+# .env.example (frontend/.env.example)
+VITE_API_BASE_URL=http://localhost:8080
+```
+
+## Performans İpuçları
+
+1. **Lazy Loading**: Sayfalar ihtiyaç anında yüklenir
+2. **Image Optimization**: Kapak resimleri lazy loading
+3. **Local Caching**: Kitaplar localStorage'da saklanır
+4. **API Debouncing**: Arama input'u için debounce eklenebilir
+
+## Erişilebilirlik
+
+- Semantic HTML kullanımı
+- Keyboard navigation desteği
+- Screen reader friendly (ikonlar için aria-label)
+
+---
+
+**İlgili Dosyalar:**
+- [Proje Genel Bakış](./proje-genel-bakis.md)
+- [Backend Yapısı](./backend-yapisi.md)
+- [Teknoloji Yığını](./teknoloji-yigini.md)
--- a/doc/proje-genel-bakis.md
+++ b/doc/proje-genel-bakis.md
@@ -0,0 +1,132 @@
+# Bookibra - Proje Genel Bakış
+
+## Proje Tanımı
+
+**Bookibra**, Amazon'dan kitap verilerini çekip sunan, barkod tarama özelliği bulunan ve kullanıcıların kendi kitap kütüphanelerini yönetebilecekleri modern bir full-stack web uygulamasıdır.
+
+## Ana Özellikler
+
+### 1. Kitap Arama ve Keşfetme
+- ISBN ile kitap arama
+- Kitap başlığı ile arama
+- Yayın tarihine göre filtreleme (örn: "Kitap Adı .2020")
+- Çoklu dil desteği (Türkçe/İngiliz Amazon siteleri)
+
+### 2. Barkod Tarama
+- Cihaz kamerası ile ISBN barkod tarama
+- Otomatik kitap bilgisi getirme
+- Mobil uyumlu tarayıcı arayüzü
+
+### 3. Kullanıcı Yönetimi
+- Kayıt olma ve giriş yapma
+- JWT tabanlı kimlik doğrulama
+- Profil yönetimi
+
+### 4. Kitap Kütüphanesi
+- Kitapları kaydetme (localStorage)
+- Kayıtlı kitapları görüntüleme
+- Kitap detaylarını inceleme
+- Kitap silme
+
+### 5. Performans ve Önbellekleme
+- Redis ile önbellekleme sistemi
+- Medya (kapak resmi) önbellekleme
+- Amazon API çağrılarını minimize etme
+
+## Mimari Genel Bakış
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                         CLIENT                               │
+│                   (React + Vite)                            │
+│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐   │
+│  │ HomePage │  │AddBooks  │  │ MyBooks  │  │ Profile  │   │
+│  └──────────┘  └──────────┘  └──────────┘  └──────────┘   │
+└─────────────────────────────────────────────────────────────┘
+                            │
+                            │ HTTP/REST
+                            ▼
+┌─────────────────────────────────────────────────────────────┐
+│                      BACKEND API                             │
+│                   (Express + Node.js)                       │
+│  ┌────────────┐  ┌────────────┐  ┌──────────────────────┐  │
+│  │ Auth Routes│  │Book Routes │  │  Middleware          │  │
+│  └────────────┘  └────────────┘  │  - Auth              │  │
+│                                   │  - Error Handler     │  │
+│  ┌────────────┐  ┌────────────┐  │  - Request Logger    │  │
+│  │ Controllers│  │ Services   │  └──────────────────────┘  │
+│  └────────────┘  └────────────┘                           │
+└─────────────────────────────────────────────────────────────┘
+                            │
+        ┌───────────────────┼───────────────────┐
+        ▼                   ▼                   ▼
+┌───────────────┐  ┌────────────────┐  ┌──────────────┐
+│    Redis      │  │   PostgreSQL   │  │   Socket.IO  │
+│   (Cache)     │  │  (Users DB)    │  │ (WebSocket)  │
+└───────────────┘  └────────────────┘  └──────────────┘
+        │
+        ▼
+┌─────────────────────────────────────────┐
+│         External Services                │
+│  ┌──────────────┐  ┌──────────────┐    │
+│  │   Amazon     │  │   Gemini AI  │    │
+│  │   Scraping   │  │   (Optional) │    │
+│  └──────────────┘  └──────────────┘    │
+└─────────────────────────────────────────┘
+```
+
+## Proje Yapısı
+
+### Dizin Hiyerarşisi
+
+```
+bookibra/
+├── doc/                    # Dokümantasyon
+├── frontend/               # React Frontend Uygulaması
+│   ├── src/
+│   │   ├── components/     # React Bileşenleri
+│   │   ├── pages/          # Sayfa Bileşenleri
+│   │   ├── context/        # React Context API
+│   │   └── main.jsx        # Uygulama Giriş Noktası
+│   └── package.json
+├── src/                    # Backend Kaynak Kodları
+│   ├── config/             # Yapılandırma Dosyaları
+│   ├── controllers/        # İstek Kontrolcüleri
+│   ├── middleware/         # Express Middleware
+│   ├── routes/             # API Rotaları
+│   ├── services/           # İş Mantığı Servisleri
+│   ├── utils/              # Yardımcı Fonksiyonlar
+│   ├── validators/         # İstek Doğrulayıcıları
+│   ├── app.js              # Express Uygulaması
+│   └── server.js           # HTTP Sunucusu
+├── docker-compose.yml      # Docker Orchestration
+├── Dockerfile              # Backend Docker Image
+└── package.json
+```
+
+## Çalışma Prensibi
+
+### Kitap Arama Akışı
+
+1. **Kullanıcı İsteği**: Frontend'den arama parametresi gönderilir
+2. **Önbellek Kontrolü**: Redis'te önceden yapılmmış arama var mı kontrol edilir
+3. **Amazon Scraping**: Önbellekte yoksa Amazon'dan veri çekilir
+4. **Veri İşleme**: HTML parse edilir ve kitap bilgileri çıkarılır
+5. **Önbellekleme**: Sonuçlar Redis'e kaydedilir
+6. **Cevap**: İşlenmiş veri frontend'e gönderilir
+
+### Barkod Tarama Akışı
+
+1. **Kamera Erişimi**: React-qr-barcode-scanner ile kamera açılır
+2. **Barkod Algılama**: ISBN formatında barkod algılanır
+3. **ISBN Arama**: Backend'e ISBN ile kitap bilgisi istenir
+4. **Kitap Gösterimi**: Bulunan kitap kullanıcıya sunulur
+
+## Deployment
+
+Uygulama Docker Compose ile tüm servisleri (frontend, backend, redis, postgres) tek seferde başlatmayı destekler.
+
+---
+
+**Son Güncelleme**: 2026-02-10
+**Versiyon**: 1.0.0
--- a/doc/teknoloji-yigini.md
+++ b/doc/teknoloji-yigini.md
@@ -0,0 +1,211 @@
+# Bookibra - Teknoloji Yığını
+
+## Teknoloji Yığınına Genel Bakış
+
+Bookibra, modern web teknolojileri ile geliştirilmiş full-stack bir uygulamadır. Aşağıda kullanılan tüm teknolojiler, neden kullanıldıkları ve projedeki rolleri detaylı olarak açıklanmıştır.
+
+## Backend Tekolojileri
+
+### Runtime ve Framework
+
+| Teknoloji | Versiyon | Kullanım Amacı | Neden Seçildi? |
+|-----------|----------|----------------|----------------|
+| **Node.js** | LTS | JavaScript runtime | Sunucu tarafında JavaScript kullanımı, büyük ekosistem, asenkron I/O |
+| **Express.js** | ^5.1.0 | Web framework | Minimal, esnek, büyük middleware ekosistemi |
+
+### Web Scraping
+
+| Teknoloji | Versiyon | Kullanım Amacı | Neden Seçildi? |
+|-----------|----------|----------------|----------------|
+| **axios** | ^1.13.2 | HTTP istekleri | Promise-based, interceptor desteği, otomatik JSON dönüşümü |
+| **cheerio** | ^1.1.2 | HTML parsing | jQuery syntax, hızlı ve hafif |
+| **szbk-amazon-book-search** | ^1.1.1 | Amazon scraping | Amazon'a özelleşmiş scraping kütüphanesi |
+
+### Veritabanı ve Önbellekleme
+
+| Teknoloji | Versiyon | Kullanım Amacı | Neden Seçildi? |
+|-----------|----------|----------------|----------------|
+| **PostgreSQL** | 8.16.3 (client) | İlişkisel veritabanı | ACID uyumlu, güçlü, açık kaynak |
+| **ioredis** | ^5.8.2 | Redis client | Promise-based, cluster desteği |
+| **Redis** | 7-alpine | Önbellekleme | In-memory store, hızlı, TTL desteği |
+
+### Kimlik Doğrulama ve Güvenlik
+
+| Teknoloji | Versiyon | Kullanım Amacı | Neden Seçildi? |
+|-----------|----------|----------------|----------------|
+| **jsonwebtoken** | ^9.0.2 | JWT token oluşturma | Stateless auth, standart, güvenli |
+| **bcrypt** | ^6.0.0 | Şifre hashleme | Güçlü hash algoritması, salting |
+| **express-validator** | ^7.3.0 | Input validation | Express ile entegre, decorator-based |
+
+### Gerçek Zamanlı İletişim
+
+| Teknoloji | Versiyon | Kullanım Amacı | Neden Seçildi? |
+|-----------|----------|----------------|----------------|
+| **Socket.IO** | ^4.8.1 | WebSocket server | Fall-back mekanizması, room desteği |
+
+### Araçlar ve Yardımcılar
+
+| Teknoloji | Versiyon | Kullanım Amacı | Neden Seçildi? |
+|-----------|----------|----------------|----------------|
+| **dotenv** | ^17.2.3 | Ortam değişkenleri | .env dosyası yönetimi |
+| **cors** | ^2.8.5 | CORS middleware | Cross-origin resource sharing |
+| **chalk** | ^4.1.2 | Terminal renklendirme | Logları okunabilir yapma |
+| **uuid** | ^13.0.0 | UUID oluşturma | Benzersiz ID oluşturma |
+| **nodemon** | ^3.1.10 | Otomatik restart | Development sırasında kolaylık |
+
+## Frontend Teknolojileri
+
+### Core Framework
+
+| Teknoloji | Versiyon | Kullanım Amacı | Neden Seçildi? |
+|-----------|----------|----------------|----------------|
+| **React** | ^19.1.1 | UI framework | Component-based, büyük ekosistem, hooks |
+| **Vite** | ^7.1.7 | Build tool ve dev server | Hızlı HMR, native ES modules |
+
+### Routing
+
+| Teknoloji | Versiyon | Kullanım Amacı | Neden Seçildi? |
+|-----------|----------|----------------|----------------|
+| **React Router** | ^7.9.5 | Client-side routing | Declarative routing, nested routes |
+
+### Animasyonlar
+
+| Teknoloji | Versiyon | Kullanım Amacı | Neden Seçildi? |
+|-----------|----------|----------------|----------------|
+| **Framer Motion** | ^12.23.24 | Animasyon library | Declarative API, gesture desteği |
+
+### İkonlar ve Görseller
+
+| Teknoloji | Versiyon | Kullanım Amacı | Neden Seçildi? |
+|-----------|----------|----------------|----------------|
+| **Font Awesome** | ^7.1.0 | İkon seti | Geniş ikon kütüphanesi |
+| **react-image-glow** | ^1.0.6 | Resim efekti | Estetik glow efekti |
+| **color-thief-react** | ^2.1.0 | Renk extract | Resimlerden ana renk alma |
+
+### Barkod Tarama
+
+| Teknoloji | Versiyon | Kullanım Amacı | Neden Seçildi? |
+|-----------|----------|----------------|----------------|
+| **react-qr-barcode-scanner** | ^2.1.18 | Barkod tarama | Hem QR hem barkod desteği |
+
+### Development Araçları
+
+| Teknoloji | Versiyon | Kullanım Amacı | Neden Seçildi? |
+|-----------|----------|----------------|----------------|
+| **ESLint** | ^9.36.0 | Linter | Kod kalitesi, tutarlılık |
+| **@vitejs/plugin-react** | ^5.0.4 | React için Vite plugin | Fast refresh, JSX support |
+
+## DevOps Teknolojileri
+
+### Containerization
+
+| Teknoloji | Versiyon | Kullanım Amacı | Neden Seçildi? |
+|-----------|----------|----------------|----------------|
+| **Docker** | Latest | Containerization | Tutarlı deployment, izolasyon |
+| **Docker Compose** | Latest | Multi-container orchestration | Local development, tüm servisleri bir arada |
+
+### Docker Hizmetleri
+
+```yaml
+services:
+  frontend:    # React uygulaması
+  api:         # Express backend
+  redis:       # Önbellekleme
+  postgres:    # Kullanıcı veritabanı
+```
+
+## Veri Akışı Diyagramı
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    USER BROWSER                              │
+│                    (React App)                               │
+└─────────────────────────────────────────────────────────────┘
+                            │
+                            │ HTTP Request
+                            ▼
+┌─────────────────────────────────────────────────────────────┐
+│                    EXPRESS SERVER                            │
+│  ┌──────────────────────────────────────────────────────┐  │
+│  │  Request Logging → Auth → Route → Controller         │  │
+│  └──────────────────────────────────────────────────────┘  │
+└─────────────────────────────────────────────────────────────┘
+                            │
+        ┌───────────────────┼───────────────────┐
+        ▼                   ▼                   ▼
+┌───────────────┐  ┌────────────────┐  ┌──────────────┐
+│     REDIS     │  │   POSTGRES     │  │   AMAZON     │
+│   Check &     │  │   User Data    │  │   Scraping   │
+│   Store       │  │   Auth         │  │   Book Data  │
+└───────────────┘  └────────────────┘  └──────────────┘
+```
+
+## Paket Yönetimi
+
+### Backend
+```bash
+npm install              # Development
+npm run dev             # Development server (nodemon)
+npm start               # Production server
+```
+
+### Frontend
+```bash
+npm install              # Development
+npm run dev             # Development server (Vite)
+npm run build           # Production build
+npm run preview         # Production preview
+```
+
+## Versiyon Yönetimi
+
+```json
+{
+  "name": "bookibra",
+  "version": "1.0.0",
+  "description": "Amazon kitap verilerini sunan Express tabanli backend"
+}
+```
+
+## Bağımlılık Yönetimi Stratejisi
+
+### Semantic Versioning
+- `^` (caret): Minor güncellemelere izin verir
+- `~` (tilde): Patch güncellemelere izin verir
+- Tam versiyon: Kilidi korur
+
+### Güvenlik
+- Düzenli `npm audit` çalıştırma
+- Vulnerability takibi
+- Güncel bağımlılıklar
+
+## Performans Optimizasyonları
+
+### Backend
+1. **Redis Önbellekleme**: 6 saat TTL ile kitap verileri önbellekte tutulur
+2. **Connection Pooling**: PostgreSQL için connection pooling
+3. **Lazy Connection**: Redis için lazy connect
+4. **Asenkron İşlemler**: Promise.all ile parallel işlemler
+
+### Frontend
+1. **Code Splitting**: Vite ile otomatik code splitting
+2. **Tree Shaking**: Kullanılmayan kod eliminasyonu
+3. **Image Optimization**: Lazy loading
+4. **Local Storage**: İstemci taraflı veri saklama
+
+## Gelecek Teknoloji Eklentileri
+
+Potansiyel iyileştirmeler:
+1. **GraphQL**: REST yerine daha verimli sorgular
+2. **TypeScript**: Tip güvenliği
+3. **Testing Framework**: Jest, Cypress
+4. **CI/CD**: GitHub Actions, GitLab CI
+5. **Monitoring**: Prometheus, Grafana
+6. **Load Balancer**: Nginx, HAProxy
+
+---
+
+**İlgili Dosyalar:**
+- [Proje Genel Bakış](./proje-genel-bakis.md)
+- [Backend Yapısı](./backend-yapisi.md)
+- [Frontend Yapısı](./frontend-yapisi.md)