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ı:

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:

// 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:

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:

{
  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:

{
  provider: 'apple' | 'google',
  onClick: () => void
}

Context Yönetimi

SavedBooksContext (src/context/SavedBooksContext.jsx)

Kitap kütüphanesi için global state yönetimi.

API:

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:

localStorage.setItem('bookibra_saved_books', JSON.stringify(savedBooks));

Stil Yapısı

Ana Layout (App.css)

Mobile Shell Pattern:

.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:

.bottom-nav {
  position: fixed;
  bottom: 0;
  width: 100%;
  display: flex;
  justify-content: space-around;
}

Renk Paleti

CSS değişkenleri ile tanımlı:

:root {
  --primary: /* Ana renk */;
  --secondary: /* İkincil renk */;
  --accent: /* Vurgu rengi */;
  --text: /* Metin rengi */;
  --bg: /* Arka plan */;
}

API Entegrasyonu

API Base URL Çözümleme

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ı

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

cd frontend
npm install
npm run dev

Production Build

npm run build
# Çıktı: dist/ dizini

Docker Build

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

# .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ış
• Backend Yapısı
• Teknoloji Yığını