# kawsaro/bookrec architecture

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

- Interactive diagram: https://gitdiagram.com/kawsaro/bookrec
- Repository: https://github.com/kawsaro/bookrec

## Overview

bookRec helps readers find legitimate free books they can comfortably read. The main journey is search, compare reading level and access, open a book, then read it in the built-in reader. The graph includes documented catalog breadth and local indexes; some source adapters and page implementations were not sampled, so their links follow README descriptions and exact paths in the tree. Search ranking, textbook course levels, library/purchase fallback, and reader controls are included as distinct capabilities.

Main entry points: [`lib/catalog.ts`](https://github.com/kawsaro/bookrec/blob/main/lib/catalog.ts) (Unified catalog), [`app/book/[ref]/page.tsx`](https://github.com/kawsaro/bookrec/blob/main/app/book/%5Bref%5D/page.tsx) (Book details), [`app/read/[ref]/page.tsx`](https://github.com/kawsaro/bookrec/blob/main/app/read/%5Bref%5D/page.tsx) (Reader page), [`components/SearchBox.tsx`](https://github.com/kawsaro/bookrec/blob/main/components/SearchBox.tsx) (Search box)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_discovery["Discovery"]
  node_home["Home<br/>[page.tsx]"]
  node_searchbox["Search box<br/>[SearchBox.tsx]"]
  node_suggest["Suggestions API<br/>[route.ts]"]
  node_searchpage["Search results<br/>[page.tsx]"]
  node_onboarding["Level setup<br/>[page.tsx]"]
  node_levelpicker["Level picker<br/>[LevelPicker.tsx]"]
end

subgraph group_catalog["Catalog and sources"]
  node_catalogsvc["Unified catalog<br/>[catalog.ts]"]
  node_gutindex[("Gutenberg index<br/>[gutenberg-index.ts]")]
  node_textindex[("Textbook index<br/>[textbook-index.ts]")]
  node_gutendex["Gutendex adapter<br/>[gutendex.ts]"]
  node_openlibrary["Open Library adapter<br/>[openlibrary.ts]"]
  node_openstax["OpenStax adapter<br/>[openstax.ts]"]
  node_textbooks["Textbook Library adapter<br/>[openstax.ts]"]
  node_othercatalogs["Other catalog adapters"]
end

subgraph group_bookinfo["Book details"]
  node_bookpage["Book details<br/>[page.tsx]"]
  node_readability["Reading-level scoring<br/>[index.ts]"]
  node_access["Purchase options<br/>[purchase.ts]"]
end

subgraph group_reading["Reading"]
  node_textloader["Text processing<br/>[gutenberg.ts]"]
  node_readpage["Reader page<br/>[page.tsx]"]
  node_readerui["Reading controls<br/>[Reader.tsx]"]
end

node_reader(("Reader"))
node_upstream{{"Book catalog services"}}
node_gutenberg{{"Project Gutenberg"}}

node_reader -->|"starts at"| node_home
node_home -->|"searches with"| node_searchbox
node_searchbox -->|"requests suggestions"| node_suggest
node_suggest -->|"queries"| node_gutindex
node_searchbox -->|"submits query"| node_searchpage
node_reader -->|"sets level"| node_onboarding
node_onboarding -->|"renders"| node_levelpicker
node_searchpage -->|"requests results"| node_catalogsvc
node_catalogsvc -->|"searches locally"| node_gutindex
node_catalogsvc -->|"searches locally"| node_textindex
node_catalogsvc -.->|"falls back to"| node_gutendex
node_catalogsvc -->|"searches"| node_openlibrary
node_catalogsvc -->|"searches"| node_openstax
node_catalogsvc -->|"searches"| node_textbooks
node_catalogsvc -->|"searches"| node_othercatalogs
node_gutendex -->|"queries"| node_upstream
node_openlibrary -->|"queries"| node_upstream
node_openstax -->|"queries"| node_upstream
node_textbooks -->|"queries"| node_upstream
node_othercatalogs -->|"queries"| node_upstream
node_searchpage -->|"opens book"| node_bookpage
node_bookpage -->|"loads book"| node_catalogsvc
node_bookpage -->|"estimates and scores"| node_readability
node_bookpage -->|"loads text for scoring"| node_textloader
node_bookpage -->|"shows purchase options"| node_access
node_textloader -->|"fetches text"| node_gutenberg
node_bookpage -->|"opens reader"| node_readpage
node_readpage -->|"loads book"| node_catalogsvc
node_readpage -->|"loads chapters"| node_textloader
node_readpage -->|"renders"| node_readerui

click node_home "https://github.com/kawsaro/bookrec/blob/main/app/page.tsx"
click node_searchbox "https://github.com/kawsaro/bookrec/blob/main/components/SearchBox.tsx"
click node_suggest "https://github.com/kawsaro/bookrec/blob/main/app/api/suggest/route.ts"
click node_searchpage "https://github.com/kawsaro/bookrec/blob/main/app/search/page.tsx"
click node_onboarding "https://github.com/kawsaro/bookrec/blob/main/app/onboarding/page.tsx"
click node_levelpicker "https://github.com/kawsaro/bookrec/blob/main/components/LevelPicker.tsx"
click node_catalogsvc "https://github.com/kawsaro/bookrec/blob/main/lib/catalog.ts"
click node_gutindex "https://github.com/kawsaro/bookrec/blob/main/lib/index/gutenberg-index.ts"
click node_textindex "https://github.com/kawsaro/bookrec/blob/main/lib/index/textbook-index.ts"
click node_gutendex "https://github.com/kawsaro/bookrec/blob/main/lib/sources/gutendex.ts"
click node_openlibrary "https://github.com/kawsaro/bookrec/blob/main/lib/sources/openlibrary.ts"
click node_openstax "https://github.com/kawsaro/bookrec/blob/main/lib/sources/openstax.ts"
click node_textbooks "https://github.com/kawsaro/bookrec/blob/main/lib/sources/openstax.ts"
click node_othercatalogs "https://github.com/kawsaro/bookrec/tree/main/lib/sources"
click node_bookpage "https://github.com/kawsaro/bookrec/blob/main/app/book/%5Bref%5D/page.tsx"
click node_readability "https://github.com/kawsaro/bookrec/blob/main/lib/readability/index.ts"
click node_access "https://github.com/kawsaro/bookrec/blob/main/lib/sources/purchase.ts"
click node_textloader "https://github.com/kawsaro/bookrec/blob/main/lib/text/gutenberg.ts"
click node_readpage "https://github.com/kawsaro/bookrec/blob/main/app/read/%5Bref%5D/page.tsx"
click node_readerui "https://github.com/kawsaro/bookrec/blob/main/components/Reader.tsx"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_home,node_searchbox,node_suggest,node_searchpage,node_onboarding,node_levelpicker toneBlue
class node_catalogsvc,node_gutindex,node_textindex,node_gutendex,node_openlibrary,node_openstax,node_textbooks,node_othercatalogs toneAmber
class node_bookpage,node_readability,node_access toneMint
class node_textloader,node_readpage,node_readerui toneRose
class node_reader,node_upstream,node_gutenberg toneIndigo
```

## Components

### Discovery

- [Home](https://github.com/kawsaro/bookrec/blob/main/app/page.tsx): `app/page.tsx`
- [Search box](https://github.com/kawsaro/bookrec/blob/main/components/SearchBox.tsx): `components/SearchBox.tsx`
- [Suggestions API](https://github.com/kawsaro/bookrec/blob/main/app/api/suggest/route.ts): `app/api/suggest/route.ts`
- [Search results](https://github.com/kawsaro/bookrec/blob/main/app/search/page.tsx): `app/search/page.tsx`
- [Level setup](https://github.com/kawsaro/bookrec/blob/main/app/onboarding/page.tsx): `app/onboarding/page.tsx`
- [Level picker](https://github.com/kawsaro/bookrec/blob/main/components/LevelPicker.tsx): `components/LevelPicker.tsx`

### Catalog and sources

- [Unified catalog](https://github.com/kawsaro/bookrec/blob/main/lib/catalog.ts): `lib/catalog.ts`
- [Gutenberg index](https://github.com/kawsaro/bookrec/blob/main/lib/index/gutenberg-index.ts): `lib/index/gutenberg-index.ts`
- [Textbook index](https://github.com/kawsaro/bookrec/blob/main/lib/index/textbook-index.ts): `lib/index/textbook-index.ts`
- [Gutendex adapter](https://github.com/kawsaro/bookrec/blob/main/lib/sources/gutendex.ts): `lib/sources/gutendex.ts`
- [Open Library adapter](https://github.com/kawsaro/bookrec/blob/main/lib/sources/openlibrary.ts): `lib/sources/openlibrary.ts`
- [OpenStax adapter](https://github.com/kawsaro/bookrec/blob/main/lib/sources/openstax.ts): `lib/sources/openstax.ts`
- [Textbook Library adapter](https://github.com/kawsaro/bookrec/blob/main/lib/sources/openstax.ts): `lib/sources/openstax.ts`
- [Other catalog adapters](https://github.com/kawsaro/bookrec/tree/main/lib/sources): `lib/sources`

### Book details

- [Book details](https://github.com/kawsaro/bookrec/blob/main/app/book/%5Bref%5D/page.tsx): `app/book/[ref]/page.tsx`
- [Reading-level scoring](https://github.com/kawsaro/bookrec/blob/main/lib/readability/index.ts): `lib/readability/index.ts`
- [Purchase options](https://github.com/kawsaro/bookrec/blob/main/lib/sources/purchase.ts): `lib/sources/purchase.ts`

### Reading

- [Text processing](https://github.com/kawsaro/bookrec/blob/main/lib/text/gutenberg.ts): `lib/text/gutenberg.ts`
- [Reader page](https://github.com/kawsaro/bookrec/blob/main/app/read/%5Bref%5D/page.tsx): `app/read/[ref]/page.tsx`
- [Reading controls](https://github.com/kawsaro/bookrec/blob/main/components/Reader.tsx): `components/Reader.tsx`

### Other components

- **Reader**
- **Book catalog services**
- **Project Gutenberg**

## Connections

- Reader → Home: starts at
- Home → Search box: searches with
- Search box → Suggestions API: requests suggestions
- Suggestions API → Gutenberg index: queries
- Search box → Search results: submits query
- Reader → Level setup: sets level
- Level setup → Level picker: renders
- Search results → Unified catalog: requests results
- Unified catalog → Gutenberg index: searches locally
- Unified catalog → Textbook index: searches locally
- Unified catalog → Gutendex adapter: falls back to
- Unified catalog → Open Library adapter: searches
- Unified catalog → OpenStax adapter: searches
- Unified catalog → Textbook Library adapter: searches
- Unified catalog → Other catalog adapters: searches
- Gutendex adapter → Book catalog services: queries
- Open Library adapter → Book catalog services: queries
- OpenStax adapter → Book catalog services: queries
- Textbook Library adapter → Book catalog services: queries
- Other catalog adapters → Book catalog services: queries
- Search results → Book details: opens book
- Book details → Unified catalog: loads book
- Book details → Reading-level scoring: estimates and scores
- Book details → Text processing: loads text for scoring
- Book details → Purchase options: shows purchase options
- Text processing → Project Gutenberg: fetches text
- Book details → Reader page: opens reader
- Reader page → Unified catalog: loads book
- Reader page → Text processing: loads chapters
- Reader page → Reading controls: renders