From 836d60da786fa5db4df5be138f452c61e385fe47 Mon Sep 17 00:00:00 2001 From: wisecolt Date: Tue, 10 Feb 2026 21:57:56 +0300 Subject: [PATCH] =?UTF-8?q?docs:=20proje=20dok=C3=BCmantasyonunu=20ekle?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit README.md ve detaylı teknik dokümantasyon dosyaları (genel bakış, backend yapısı, frontend yapısı, teknoloji yığını) eklendi. --- README.md | 299 +++++++++++++++++++++++++++++++++ doc/backend-yapisi.md | 351 +++++++++++++++++++++++++++++++++++++++ doc/frontend-yapisi.md | 341 +++++++++++++++++++++++++++++++++++++ doc/proje-genel-bakis.md | 132 +++++++++++++++ doc/teknoloji-yigini.md | 211 +++++++++++++++++++++++ 5 files changed, 1334 insertions(+) create mode 100644 README.md create mode 100644 doc/backend-yapisi.md create mode 100644 doc/frontend-yapisi.md create mode 100644 doc/proje-genel-bakis.md create mode 100644 doc/teknoloji-yigini.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..e79ca54 --- /dev/null +++ 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. diff --git a/doc/backend-yapisi.md b/doc/backend-yapisi.md new file mode 100644 index 0000000..5f58c64 --- /dev/null +++ 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) diff --git a/doc/frontend-yapisi.md b/doc/frontend-yapisi.md new file mode 100644 index 0000000..9657789 --- /dev/null +++ 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) diff --git a/doc/proje-genel-bakis.md b/doc/proje-genel-bakis.md new file mode 100644 index 0000000..cf545d0 --- /dev/null +++ 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 diff --git a/doc/teknoloji-yigini.md b/doc/teknoloji-yigini.md new file mode 100644 index 0000000..d5cdd16 --- /dev/null +++ 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)