# numulix/booklookup architecture

> Architecture diagram of the GitHub repository numulix/booklookup, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/numulix/booklookup
- Repository: https://github.com/numulix/booklookup

## Overview

##### Project Type & Purpose
- This is a single‐page web application (SPA) built with React and Vite.
- Its purpose is to let users search for books via the Open Library API, display results, view details, and keep track of viewed books.

##### Key Architectural Components
a. Browser / Client
- Renders `index.html` and runs the React bundle delivered by Vite.
b. Build & Deployment (Vite)
- Vite compiles TSX, CSS, assets into a static bundle, served from `/public`.
c. Routing Layer
- `routes.ts` + React Router v7 defines URL→Page mapping (LandingPage, BookDetailsPage).
d. Presentation Layer (Pages & UI Components)
- Pages (`src/pages`) compose Layout + feature components.
- UI components (`src/components/ui`) render lists, loading/error states, search bar.
- Layout component (`src/components/layout/Layout.tsx`) provides common header/footer.
e. State Management
- Redux Toolkit (`src/store/index.ts`) with RTK Query (`src/store/api/bookApi.ts`) for remote data fetch, caching, invalidation.
- `ViewedBooksContext` tracks books the user has seen locally (Context API).
f. Business Logic & Hooks
- Custom hook `useBookSearch` abstracts search logic, calls RTK Query endpoints.
- Feature‐level components (`src/features`) wire UI → hooks → store.
g. Utility & Types
- Shared utils (`src/utils/bookUtils.ts`) for data transformations.
- Type definitions in `src/types` enforce consistency.

##### External Dependencies
- Open Library API (external REST service): search and retrieve book metadata.
- Tailwind v4 for styling.
- Prettier & ESLint for code quality.

## Diagram (Mermaid)

```mermaid
flowchart TD
  subgraph "Build & Deployment"
    VITE["Vite Build"]:::build
    PUBLIC["public/"]:::build
    VITE -->|"outputs bundle"| PUBLIC
    click VITE "https://github.com/numulix/booklookup/blob/main/vite.config.ts"
    click PUBLIC "https://github.com/numulix/booklookup/tree/main/public/"
  end

  subgraph "Browser / Client"
    CLIENTHTML["index.html"]:::build
    MAIN["src/main.tsx"]:::build
    APP["src/App.tsx"]:::build
    CLIENTHTML --> MAIN --> APP

    subgraph "Routing Layer"
      ROUTES["src/routes.ts"]:::router
      click ROUTES "https://github.com/numulix/booklookup/blob/main/src/routes.ts"
    end

    subgraph "Presentation Layer"
      subgraph "Pages"
        LANDING["LandingPage"]:::ui
        click LANDING "https://github.com/numulix/booklookup/blob/main/src/pages/LandingPage.tsx"
        DETAILS["BookDetailsPage"]:::ui
        click DETAILS "https://github.com/numulix/booklookup/blob/main/src/pages/BookDetailsPage.tsx"
        PAGESINDEX["src/pages/index.ts"]:::ui
        click PAGESINDEX "https://github.com/numulix/booklookup/blob/main/src/pages/index.ts"
      end

      subgraph "Layout"
        LAYOUT["Layout"]:::ui
        click LAYOUT "https://github.com/numulix/booklookup/blob/main/src/components/layout/Layout.tsx"
      end

      subgraph "UI Components"
        BOOKLIST["BookList"]:::ui
        click BOOKLIST "https://github.com/numulix/booklookup/blob/main/src/components/ui/BookList.tsx"
        BOOKITEM["BookListItem"]:::ui
        click BOOKITEM "https://github.com/numulix/booklookup/blob/main/src/components/ui/BookListItem.tsx"
        SEARCH["SearchBar"]:::ui
        click SEARCH "https://github.com/numulix/booklookup/blob/main/src/components/ui/SearchBar.tsx"
        LOADING["BookDetailsLoading"]:::ui
        click LOADING "https://github.com/numulix/booklookup/blob/main/src/components/ui/BookDetailsLoading.tsx"
        ERROR["BookDetailsError"]:::ui
        click ERROR "https://github.com/numulix/booklookup/blob/main/src/components/ui/BookDetailsError.tsx"
        UIINDEX["ui index"]:::ui
        click UIINDEX "https://github.com/numulix/booklookup/blob/main/src/components/ui/index.ts"
      end
    end

    subgraph "Business Logic & Hooks"
      HOOK["useBookSearch"]:::hook
      click HOOK "https://github.com/numulix/booklookup/blob/main/src/hooks/useBookSearch.ts"
    end

    subgraph "State Management"
      STORE["Redux Store"]:::state
      click STORE "https://github.com/numulix/booklookup/blob/main/src/store/index.ts"
      API["bookApi (RTK Query)"]:::state
      click API "https://github.com/numulix/booklookup/blob/main/src/store/api/bookApi.ts"
      CONTEXT["ViewedBooksContext"]:::state
      click CONTEXT "https://github.com/numulix/booklookup/blob/main/src/context/ViewedBooksContext.tsx"
    end

    subgraph "Utilities & Types"
      UTILS["bookUtils"]:::util
      click UTILS "https://github.com/numulix/booklookup/blob/main/src/utils/bookUtils.ts"
      UTILSINDEX["utils index"]:::util
      click UTILSINDEX "https://github.com/numulix/booklookup/blob/main/src/utils/index.ts"
      TYPESBOOK["book types"]:::util
      click TYPESBOOK "https://github.com/numulix/booklookup/blob/main/src/types/book.ts"
      TYPESINDEX["types index"]:::util
      click TYPESINDEX "https://github.com/numulix/booklookup/blob/main/src/types/index.ts"
    end

    APP --> ROUTES
    ROUTES --> LANDING
    ROUTES --> DETAILS
    LANDING --> BOOKLIST
    LANDING --> SEARCH
    DETAILS --> LOADING
    DETAILS --> ERROR
    SEARCH -->|"search(query)"| HOOK
    BOOKLIST -->|"selectBook(id)"| HOOK
    HOOK -->|"dispatch search endpoint"| API
    API -->|"GET /search?q"| EXTERNAL
    EXTERNAL -->|"QueryResult"| API
    API -->|"cache result"| STORE
    STORE -->|"provide data"| HOOK
    HOOK -->|"return data"| BOOKLIST
    BOOKITEM -->|"view details"| CONTEXT
  end

  subgraph "External Services"
    EXTERNAL["Open Library API"]:::external
  end

  classDef ui fill:#E0F7FA,stroke:#006064;
  classDef state fill:#E8F5E9,stroke:#1B5E20;
  classDef build fill:#F5F5F5,stroke:#616161;
  classDef external fill:#FFF3E0,stroke:#E65100;
  classDef hook fill:#EDE7F6,stroke:#4527A0;
  classDef util fill:#E3F2FD,stroke:#0D47A1;
```
