bookibra/doc/frontend-yapisi.md

# 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)