# devwonny/bookmarker architecture

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

- Interactive diagram: https://gitdiagram.com/devwonny/bookmarker
- Repository: https://github.com/devwonny/bookmarker

## Overview

##### Project type and purpose
- This is a full-stack Next.js web application (“Bookmarker”) that lets users search books (via the Aladin Open API), view details, find nearby bookstores, and maintain a local “wishlist.” It uses Next.js 13’s App Router, custom API routes under app/api/aladin, server & client components, and Zustand for client state.

##### File structure
- Top-level “app” directory: Next.js App Router pages and layouts, plus built-in API routes under app/api/aladin/bookList and bookSearch.
- “components”: React UI components (common, modals, bookstoreLocation).
- “services/book.ts”: abstraction over Aladin API calls, used by app/api routes.
- “utils/removeText.ts”: helper for text processing.
- “styles” & “public”: SCSS and static assets.
- “types”: shared TypeScript types.
- No external database: wishlist likely stored client-side (Zustand or localStorage).

##### README for additional insights
- Pages: Main, Search Results, Book Detail, Bookstore Location, Wishlist.

a. Main components:
- Client (Browser) – renders React pages + components, holds local state (Zustand)
- Next.js Server – hosts App Router pages + server components + API Routes
- API Routes (app/api/aladin/*) – serverless functions that proxy/fetch from the external Aladin API
- External Service – Aladin Open API endpoint(s)
- Assets & Styles – SCSS/Tailwind, public/static assets

b. Relationships & Data Flows:
1. Browser → Next.js Page (SSR or CSR)
2. Page invokes fetch()/useEffect or built-in Server Component fetch to Next.js API Route (or directly to Aladin if SSR)
3. API Route → Service Layer (services/book.ts) → External Aladin API → back to API Route → Next.js Page → Browser
4. Client State (Zustand) manages user interactions (wishlist additions/removals) purely in-browser

c. Architectural patterns & principles:
- Monolithic web app with built-in serverless API routes
- Separation of concerns: UI components vs data-fetching services vs route wiring
- Next.js App Router: clear division between server and client components (layout.tsx vs layoutClient.tsx)
- Unidirectional data flow: external API → service → route → page → UI
- Client state isolation (Zustand) for ephemeral/persistent UI state

d. Key technologies & libraries:
- Next.js 13 (App Router, Server Components, API Routes)
- TypeScript (types/ folder)
- Zustand (client state)
- SCSS + Tailwind (styles/)
- react-toastify, swiper, mui (UI extras)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Presentation Layer
    subgraph "Presentation Layer (Browser UI)" 
        direction TB
        Browser["Browser + Zustand (Wishlist)"]:::client
        MainPage["Main Page"]:::client
        SearchResults["Search Results Page"]:::client
        BookDetail["Book Detail Page"]:::client
        BookstoreLocation["Bookstore Location Page"]:::client
        WishlistPage["Wishlist Page"]:::client
    end

    %% Next.js Server Layer
    subgraph "Next.js Server" 
        direction TB
        RootLayout["Root Layout (Server Component)"]:::server
        RootClientLayout["Root Client Layout"]:::client
        API_BookSearch["API Route: /api/aladin/bookSearch"]:::api
        API_BookList["API Route: /api/aladin/bookList"]:::api
    end

    %% Service Layer
    subgraph "Service & Utils" 
        direction TB
        ServiceBook["services/book.ts"]:::service
        UtilsRemoveText["utils/removeText.ts"]:::service
    end

    %% External Layer
    subgraph "External Services" 
        direction TB
        AladinAPI["Aladin Open API"]:::external
    end

    %% Data Flow Links
    Browser -->|renders| MainPage
    Browser -->|renders| SearchResults
    Browser -->|renders| BookDetail
    Browser -->|renders| BookstoreLocation
    Browser -->|renders| WishlistPage

    MainPage -->|uses Layout| RootLayout
    SearchResults -->|uses Layout| RootLayout
    BookDetail -->|uses Layout| RootLayout
    BookstoreLocation -->|uses Layout| RootLayout
    WishlistPage -->|uses Layout| RootLayout

    RootLayout -->|wraps with| RootClientLayout

    SearchResults -->|SSR/CSR fetch| API_BookSearch
    BookDetail -->|SSR/CSR fetch| API_BookList

    API_BookSearch -->|calls| ServiceBook
    API_BookList -->|calls| ServiceBook

    ServiceBook -->|uses| UtilsRemoveText
    ServiceBook -->|fetches from| AladinAPI

    AladinAPI -->|response| ServiceBook
    ServiceBook -->|returns data| API_BookSearch
    ServiceBook -->|returns data| API_BookList

    API_BookSearch -->|response| SearchResults
    API_BookList -->|response| BookDetail

    WishlistPage -->|updates| Browser

    %% Click Events
    click MainPage "https://github.com/devwonny/bookmarker/blob/main/app/page.tsx"
    click SearchResults "https://github.com/devwonny/bookmarker/blob/main/app/bookResult/page.tsx"
    click BookDetail "https://github.com/devwonny/bookmarker/blob/main/app/bookDetail/page.tsx"
    click BookstoreLocation "https://github.com/devwonny/bookmarker/blob/main/app/bookstoreLocation/page.tsx"
    click WishlistPage "https://github.com/devwonny/bookmarker/blob/main/app/wishlist/page.tsx"
    click RootLayout "https://github.com/devwonny/bookmarker/blob/main/app/layout.tsx"
    click RootClientLayout "https://github.com/devwonny/bookmarker/blob/main/app/layoutClient.tsx"
    click API_BookSearch "https://github.com/devwonny/bookmarker/blob/main/app/api/aladin/bookSearch/route.ts"
    click API_BookList "https://github.com/devwonny/bookmarker/blob/main/app/api/aladin/bookList/route.ts"
    click ServiceBook "https://github.com/devwonny/bookmarker/blob/main/services/book.ts"
    click UtilsRemoveText "https://github.com/devwonny/bookmarker/blob/main/utils/removeText.ts"

    %% Styles & Assets (Annotations)
    classDef client fill:#D0E8FF,stroke:#007acc,color:#000
    classDef server fill:#DFFFE0,stroke:#0a8a00,color:#000
    classDef api fill:#E8FFE8,stroke:#00a000,color:#000
    classDef service fill:#F0F0F0,stroke:#888888,color:#000
    classDef external fill:#FFEFD5,stroke:#FF8C00,color:#000
```
