ShareBook — platforma wypożyczania książek w lokalnej społeczności

Projekt rozwiązuje konkretny problem: zamiast kupować książkę, którą przeczytasz raz, możesz wypożyczyć ją od kogoś z okolicy. Każdy użytkownik skanuje ISBN posiadanych książek — resztą zajmuje się aplikacja: wyszukuje metadane (tytuł, autor, gatunek, opis), pobiera lub generuje okładkę i wystawia egzemplarz do wypożyczenia przez społeczność.

Backend zbudowany jest na FastAPI z async SQLAlchemy 2.0, z pełną warstwą interfejsów serwisów (Protocol), rate limitingiem (slowapi), walidacją siły hasła (zxcvbn), strukturyzowanymi logami (structlog) i typowaniem przez mypy. Frontend używa TanStack React Query do cache’owania i synchronizacji stanu serwera oraz Zustand do lokalnego stanu biblioteki użytkownika.

01Funkcjonalności

02Architektura systemu

03Interfejs — ciepła estetyka biblioteki

Frontend utrzymany jest w palecie warm-beige (#FAF7F2), złota book-gold (#C4A77D) i głębokiej brązu book-brown (#2D2A26). Nagłówki w Playfair Display (serif, elegancki), treść w Inter. Karty książek mają cień shadow-book i unoszą się przy hoverze o 8px z mocniejszym cieniem. Scrollbar w kolorze złota — każdy element interfejsu spójny z klimatem tradycyjnej biblioteki.

Ekrany aplikacji

• Landing page — strona powitalna z sekcją “jak to działa”, CTA do rejestracji
• Browse — katalog książek społeczności, filtry, karty z okładką, autorem, statusem dostępności
• Book Detail — szczegóły książki, status egzemplarzy, przycisk prośby o wypożyczenie
• Reader Panel — moje książki / wypożyczone / oddane / prośby przychodzące i wychodzące
• Add Book Dialog — dodanie przez ISBN: agent AI zwraca metadane, podgląd okładki generowanej live przez WebSocket
• AI Chat — rozmowa z asystentem-bibliotekarzem, wyniki z podaniem źródeł (tytuł, autor, similarity score)
• Profile — edycja profilu, zmiana hasła, liczba posiadanych książek
• Admin Panel — Dashboard / Users / Books / User Books — 4 sekcje na jednej stronie z Tabs

04Trzy warstwy AI

1. BookSearchAgent — metadane przez OpenAI web search

Gdy użytkownik wpisuje ISBN, aplikacja nie odpytuje tylko Open Library — uruchamia agenta OpenAI z narzędziem web_search, który szuka informacji o książce w internecie i zwraca ustrukturyzowany JSON (tytuł, autor, opis, gatunek, ISBN-13, rok wydania). Fallback na Open Library jeśli OpenAI jest niedostępny.

async def search(self, query: str) -> BookData:
    search_query = self.query_builder.build(query)

    response = await self.client.responses.create(
        model=self.model,
        tools=[{"type": "web_search"}],  # ← OpenAI web_search tool
        input=[
            {"role": "system", "content": self.query_builder.get_system_prompt()},
            {"role": "user",   "content": self.query_builder.build_prompt(search_query)}
        ]
    )
    llm_data = self._extract_json(response.output_text)
    cover_url = await self._get_cover_url(llm_data, search_query.normalized_isbn)
    return self.result_formatter.format(llm_data, cover_url)

2. AIService — chatbot-bibliotekarz z RAG

Zapytanie użytkownika (“coś o podróżach po Azji”) jest zamieniane na embedding, który trafia do pgvector i szuka semantycznie podobnych fragmentów opisów książek z katalogu. Znalezione chunki wchodzą jako kontekst do promptu systemowego — model odpowiada wyłącznie na ich podstawie, bez wymyślania nieistniejących tytułów. Odpowiedź zawiera listę źródeł z similarity score.

3. CoverAIGenerator — okładki przez DALL-E 3

Gdy okładka nie jest dostępna w Open Library, serwis generuje ją przez DALL-E 3. Prompt zapewnia, że okładka jest artystyczna, bez tekstu i liter, w proporcjach pionowej książki, skalowana przez PIL do 180px szerokości z crop do proporcji 1:1.5. Wynik jest serwowany przez StaticFiles /covers. Generowanie przebiega asynchronicznie — frontend jest informowany przez WebSocket gdy okładka jest gotowa.

prompt = (
    f"Professional book cover design for '{title}' by {author}.{genre_hint} "
    f"Artistic cover, no text, no letters, no words, "
    f"vertical book cover proportions, high quality, "
    f"minimalist design suitable for 180px thumbnail"
)
response = await self.client.images.generate(
    model="dall-e-3", prompt=prompt,
    size="1024x1024", quality="standard", n=1
)
# → PIL resize do 180×270px → zapis do /covers/{isbn}.jpg

05WebSocket — real-time w dwóch miejscach

Backend ma pełny WebSocketManager z trzema komponentami: ConnectionRegistry (aktywne połączenia + ping/pong), SubscriptionManager (subskrypcje book_id → lista socketów) i Broadcaster (send personal + broadcast to book).

• Cover live preview — po wysłaniu ISBN do API frontend subskrybuje WebSocket na book_id. Gdy serwer skończy generować okładkę, broadcastuje {type: "cover_ready", url: "..."} do wszystkich subskrybentów. Hook useBookCoverWS odbiera wiadomość i aktualizuje UI bez odświeżania strony.
• Chat wypożyczenia — wiadomości między użytkownikiem a właścicielem w czasie rzeczywistym, z obsługą statusu przeczytana/nieprzeczytana i typami wiadomości (text, zdarzenia systemowe).

06Autentykacja — triple-cookie JWT

Zamiast przechowywania tokenów w localStorage (podatne na XSS), ShareBook używa trzech cookies ustawianych przez serwer:

• access_token — JWT (30 minut), httpOnly=True, SameSite=Lax — niedostępny dla JS
• refresh_token — JWT (7 dni), httpOnly=True — używany do cichego odświeżenia access tokena
• csrf_token — httpOnly=False, odczytywany przez JS i dołączany do nagłówka każdego żądania modyfikującego dane

Dodatkowe zabezpieczenia: rate limiting przez slowapi (limit na endpoint logowania), bcrypt z 12 rundami (BCRYPT_ROUNDS), walidacja siły hasła przez bibliotekę zxcvbn i token blacklist dla wylogowanych tokenów.

def verify_csrf_token(token: str, cookie_token: str) -> bool:
    if not token or not cookie_token:
        return False
    if len(token.encode('utf-8')) < 32:
        return False
    return secrets.compare_digest(token, cookie_token)
    # ↑ compare_digest zapobiega timing attacks

07Stack technologiczny

08Struktura projektu

Wzorce architektoniczne

• Interface Segregation (Protocol) — każdy serwis ma swój interface ABC (IBookService, IAIService…). Endpointy zależą od abstrakcji, nie od konkretnych implementacji
• Repository Pattern — warstwa dostępu do danych oddzielona od logiki biznesowej (6 repozytoriów)
• Service Factory — factories.py tworzy i wstrzykuje serwisy, odwrócenie zależności przez FastAPI Depends()
• Domain Exceptions — hierarchia ShareBookException mapowana na kody HTTP w globalnym handlerze

09Model danych

Sześć encji w PostgreSQL, w tym BookChunk z kolumną Vector(1536) dla RAG:

10REST API — wybrane endpointy

11Testowanie

Projekt ma skonfigurowane środowiska testowe zarówno po stronie backendowej jak i frontendowej:

• Backend — pytest + pytest-asyncio + httpx jako async test client dla FastAPI. Konfiguracja mypy (mypy.ini) + ruff jako linter
• Frontend — vitest z konfiguracją w vitest.config.ts, uruchamiany przez npm test, z opcją --coverage
• Seed danych — scripts/seed_database.py z 50+ książkami (dane JSON) do natychmiastowego załadowania środowiska dev

12Czego dowodzi ten projekt