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.
This commit is contained in:
299
README.md
Normal file
299
README.md
Normal file
@@ -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.
|
||||
Reference in New Issue
Block a user