# jraversbcn21/lecturamepdf architecture

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

- Interactive diagram: https://gitdiagram.com/jraversbcn21/lecturamepdf
- Repository: https://github.com/jraversbcn21/lecturamepdf

## Overview

LecturamePDF is a browser-based PDF listening reader. The main workflow takes a selected PDF through local extraction and document persistence, then opens it in a reader that coordinates speech, progress, search, outline, bookmarks, and the original PDF. Optional sync transfers library metadata and PDFs between devices; optional AI speech uses OpenRouter. The README documents PWA/offline support, but the sampled sources do not show its runtime implementation, so it is represented without an asserted connection. Edges reflect excerpts, SOURCE INDEX references, or README statements; unsampled relationships are omitted.

Main entry points: [`src/app/components/Reader.tsx`](https://github.com/jraversbcn21/lecturamepdf/blob/main/src/app/components/Reader.tsx) (Reader coordinator), [`src/app/App.tsx`](https://github.com/jraversbcn21/lecturamepdf/blob/main/src/app/App.tsx) (App shell), [`src/core/storage.ts`](https://github.com/jraversbcn21/lecturamepdf/blob/main/src/core/storage.ts) (IndexedDB storage), [`src/app/usePlayer.ts`](https://github.com/jraversbcn21/lecturamepdf/blob/main/src/app/usePlayer.ts) (Playback hook)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["PDF ingestion"]
  node_app["App shell<br/>[App.tsx]"]
  node_library["Library<br/>[Library.tsx]"]
  node_extract["PDF extraction<br/>[extract.ts]"]
  node_layout["PDF layout<br/>[layout.ts]"]
  node_sentences["Sentence splitting<br/>[sentences.ts]"]
end

subgraph group_reading["Reading experience"]
  node_reader["Reader coordinator<br/>[Reader.tsx]"]
  node_view["Text view<br/>[ReaderView.tsx]"]
  node_controls["Player controls<br/>[PlayerControls.tsx]"]
  node_player["Playback hook<br/>[usePlayer.ts]"]
  node_reducer["Player state<br/>[playerReducer.ts]"]
end

subgraph group_domain["Document features"]
  node_outline["Section outline<br/>[outline.ts]"]
  node_outlineui["Outline panel<br/>[Outline.tsx]"]
  node_search["Document search<br/>[search.ts]"]
  node_searchui["Search panel<br/>[Search.tsx]"]
  node_bookmarkcore["Bookmark logic<br/>[bookmarks.ts]"]
  node_bookmarkhook["Bookmark state<br/>[useBookmarks.ts]"]
  node_bookmarkui["Bookmarks panel<br/>[Bookmarks.tsx]"]
  node_pdfpane["Original PDF pane<br/>[PdfPane.tsx]"]
end

subgraph group_persistence["Local and sync storage"]
  node_storage[("IndexedDB storage<br/>[storage.ts]")]
  node_sync["Sync client<br/>[sync.ts]"]
  node_syncapi["Sync API<br/>[library.ts]"]
  node_fileapi["PDF API<br/>[file.ts]"]
end

subgraph group_speech["Speech integrations"]
  node_browser["Browser speech"]
  node_tts["Speech engine<br/>[tts.ts]"]
  node_openrouter["OpenRouter"]
end

node_user(("Reader"))

node_user -->|"chooses PDF"| node_app
node_app -->|"shows library"| node_library
node_app -->|"extracts PDF"| node_extract
node_extract -->|"reconstructs layout"| node_layout
node_extract -->|"splits text"| node_sentences
node_app -->|"saves document"| node_storage
node_app -->|"opens document"| node_reader
node_library -->|"loads library"| node_storage
node_reader -->|"starts playback"| node_player
node_reader -->|"renders reading view"| node_view
node_reader -->|"renders controls"| node_controls
node_controls -->|"dispatches actions"| node_player
node_player -->|"updates state"| node_reducer
node_player -->|"speaks sentences"| node_tts
node_player -->|"saves progress"| node_storage
node_tts -->|"uses synthesis"| node_browser
node_tts -.->|"requests AI speech"| node_openrouter
node_reader -->|"builds section state"| node_outline
node_reader -->|"renders outline"| node_outlineui
node_outlineui -->|"derives headings"| node_outline
node_reader -->|"queries document"| node_search
node_reader -->|"renders search"| node_searchui
node_searchui -->|"finds matches"| node_search
node_reader -->|"manages bookmarks"| node_bookmarkhook
node_bookmarkhook -->|"updates markers"| node_bookmarkcore
node_bookmarkhook -->|"persists markers"| node_storage
node_reader -->|"renders bookmarks"| node_bookmarkui
node_reader -->|"renders original PDF"| node_pdfpane
node_pdfpane -.->|"loads saved PDF"| node_storage
node_app -->|"syncs library"| node_sync
node_sync -->|"applies merged data"| node_storage
node_sync -.->|"syncs metadata"| node_syncapi
node_sync -.->|"transfers PDF"| node_fileapi

click node_app "https://github.com/jraversbcn21/lecturamepdf/blob/main/src/app/App.tsx"
click node_library "https://github.com/jraversbcn21/lecturamepdf/blob/main/src/app/components/Library.tsx"
click node_extract "https://github.com/jraversbcn21/lecturamepdf/blob/main/src/core/pdf/extract.ts"
click node_layout "https://github.com/jraversbcn21/lecturamepdf/blob/main/src/core/pdf/layout.ts"
click node_sentences "https://github.com/jraversbcn21/lecturamepdf/blob/main/src/core/sentences.ts"
click node_reader "https://github.com/jraversbcn21/lecturamepdf/blob/main/src/app/components/Reader.tsx"
click node_view "https://github.com/jraversbcn21/lecturamepdf/blob/main/src/app/components/ReaderView.tsx"
click node_controls "https://github.com/jraversbcn21/lecturamepdf/blob/main/src/app/components/PlayerControls.tsx"
click node_player "https://github.com/jraversbcn21/lecturamepdf/blob/main/src/app/usePlayer.ts"
click node_reducer "https://github.com/jraversbcn21/lecturamepdf/blob/main/src/app/playerReducer.ts"
click node_outline "https://github.com/jraversbcn21/lecturamepdf/blob/main/src/core/outline.ts"
click node_outlineui "https://github.com/jraversbcn21/lecturamepdf/blob/main/src/app/components/Outline.tsx"
click node_search "https://github.com/jraversbcn21/lecturamepdf/blob/main/src/core/search.ts"
click node_searchui "https://github.com/jraversbcn21/lecturamepdf/blob/main/src/app/components/Search.tsx"
click node_bookmarkcore "https://github.com/jraversbcn21/lecturamepdf/blob/main/src/core/bookmarks.ts"
click node_bookmarkhook "https://github.com/jraversbcn21/lecturamepdf/blob/main/src/app/useBookmarks.ts"
click node_bookmarkui "https://github.com/jraversbcn21/lecturamepdf/blob/main/src/app/components/Bookmarks.tsx"
click node_pdfpane "https://github.com/jraversbcn21/lecturamepdf/blob/main/src/app/components/PdfPane.tsx"
click node_storage "https://github.com/jraversbcn21/lecturamepdf/blob/main/src/core/storage.ts"
click node_sync "https://github.com/jraversbcn21/lecturamepdf/blob/main/src/core/sync.ts"
click node_syncapi "https://github.com/jraversbcn21/lecturamepdf/blob/main/api/library.ts"
click node_fileapi "https://github.com/jraversbcn21/lecturamepdf/blob/main/api/file.ts"
click node_tts "https://github.com/jraversbcn21/lecturamepdf/blob/main/src/core/tts.ts"

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_app,node_library,node_extract,node_layout,node_sentences toneBlue
class node_reader,node_view,node_controls,node_player,node_reducer toneAmber
class node_outline,node_outlineui,node_search,node_searchui,node_bookmarkcore,node_bookmarkhook,node_bookmarkui,node_pdfpane toneMint
class node_storage,node_sync,node_syncapi,node_fileapi toneRose
class node_browser,node_tts,node_openrouter,node_user toneIndigo
```

## Components

### PDF ingestion

- [App shell](https://github.com/jraversbcn21/lecturamepdf/blob/main/src/app/App.tsx): `src/app/App.tsx`
- [Library](https://github.com/jraversbcn21/lecturamepdf/blob/main/src/app/components/Library.tsx): `src/app/components/Library.tsx`
- [PDF extraction](https://github.com/jraversbcn21/lecturamepdf/blob/main/src/core/pdf/extract.ts): `src/core/pdf/extract.ts`
- [PDF layout](https://github.com/jraversbcn21/lecturamepdf/blob/main/src/core/pdf/layout.ts): `src/core/pdf/layout.ts`
- [Sentence splitting](https://github.com/jraversbcn21/lecturamepdf/blob/main/src/core/sentences.ts): `src/core/sentences.ts`

### Reading experience

- [Reader coordinator](https://github.com/jraversbcn21/lecturamepdf/blob/main/src/app/components/Reader.tsx): `src/app/components/Reader.tsx`
- [Text view](https://github.com/jraversbcn21/lecturamepdf/blob/main/src/app/components/ReaderView.tsx): `src/app/components/ReaderView.tsx`
- [Player controls](https://github.com/jraversbcn21/lecturamepdf/blob/main/src/app/components/PlayerControls.tsx): `src/app/components/PlayerControls.tsx`
- [Playback hook](https://github.com/jraversbcn21/lecturamepdf/blob/main/src/app/usePlayer.ts): `src/app/usePlayer.ts`
- [Player state](https://github.com/jraversbcn21/lecturamepdf/blob/main/src/app/playerReducer.ts): `src/app/playerReducer.ts`

### Document features

- [Section outline](https://github.com/jraversbcn21/lecturamepdf/blob/main/src/core/outline.ts): `src/core/outline.ts`
- [Outline panel](https://github.com/jraversbcn21/lecturamepdf/blob/main/src/app/components/Outline.tsx): `src/app/components/Outline.tsx`
- [Document search](https://github.com/jraversbcn21/lecturamepdf/blob/main/src/core/search.ts): `src/core/search.ts`
- [Search panel](https://github.com/jraversbcn21/lecturamepdf/blob/main/src/app/components/Search.tsx): `src/app/components/Search.tsx`
- [Bookmark logic](https://github.com/jraversbcn21/lecturamepdf/blob/main/src/core/bookmarks.ts): `src/core/bookmarks.ts`
- [Bookmark state](https://github.com/jraversbcn21/lecturamepdf/blob/main/src/app/useBookmarks.ts): `src/app/useBookmarks.ts`
- [Bookmarks panel](https://github.com/jraversbcn21/lecturamepdf/blob/main/src/app/components/Bookmarks.tsx): `src/app/components/Bookmarks.tsx`
- [Original PDF pane](https://github.com/jraversbcn21/lecturamepdf/blob/main/src/app/components/PdfPane.tsx): `src/app/components/PdfPane.tsx`

### Local and sync storage

- [IndexedDB storage](https://github.com/jraversbcn21/lecturamepdf/blob/main/src/core/storage.ts): `src/core/storage.ts`
- [Sync client](https://github.com/jraversbcn21/lecturamepdf/blob/main/src/core/sync.ts): `src/core/sync.ts`
- [Sync API](https://github.com/jraversbcn21/lecturamepdf/blob/main/api/library.ts): `api/library.ts`
- [PDF API](https://github.com/jraversbcn21/lecturamepdf/blob/main/api/file.ts): `api/file.ts`

### Speech integrations

- **Browser speech**
- [Speech engine](https://github.com/jraversbcn21/lecturamepdf/blob/main/src/core/tts.ts): `src/core/tts.ts`
- **OpenRouter**

### Other components

- **Reader**

## Connections

- Reader → App shell: chooses PDF (evidence: `README.md`)
- App shell → Library: shows library (evidence: `src/app/App.tsx`)
- App shell → PDF extraction: extracts PDF (evidence: `src/app/App.tsx`)
- PDF extraction → PDF layout: reconstructs layout (evidence: `src/core/pdf/extract.ts`)
- PDF extraction → Sentence splitting: splits text (evidence: `src/core/pdf/extract.ts`)
- App shell → IndexedDB storage: saves document (evidence: `src/app/App.tsx`)
- App shell → Reader coordinator: opens document (evidence: `src/app/App.tsx`)
- Library → IndexedDB storage: loads library (evidence: `src/app/components/Library.tsx`)
- Reader coordinator → Playback hook: starts playback (evidence: `src/app/components/Reader.tsx`)
- Reader coordinator → Text view: renders reading view (evidence: `src/app/components/Reader.tsx`)
- Reader coordinator → Player controls: renders controls (evidence: `src/app/components/Reader.tsx`)
- Player controls → Playback hook: dispatches actions (evidence: `src/app/components/PlayerControls.tsx`)
- Playback hook → Player state: updates state (evidence: `src/app/usePlayer.ts`)
- Playback hook → Speech engine: speaks sentences (evidence: `src/app/usePlayer.ts`)
- Playback hook → IndexedDB storage: saves progress (evidence: `src/app/usePlayer.ts`)
- Speech engine → Browser speech: uses synthesis (evidence: `src/core/tts.ts`)
- Speech engine → OpenRouter: requests AI speech (evidence: `src/core/tts.ts`)
- Reader coordinator → Section outline: builds section state (evidence: `src/app/components/Reader.tsx`)
- Reader coordinator → Outline panel: renders outline (evidence: `src/app/components/Reader.tsx`)
- Outline panel → Section outline: derives headings (evidence: `src/app/components/Outline.tsx`)
- Reader coordinator → Document search: queries document (evidence: `src/app/components/Reader.tsx`)
- Reader coordinator → Search panel: renders search (evidence: `src/app/components/Reader.tsx`)
- Search panel → Document search: finds matches (evidence: `src/app/components/Search.tsx`)
- Reader coordinator → Bookmark state: manages bookmarks (evidence: `src/app/components/Reader.tsx`)
- Bookmark state → Bookmark logic: updates markers (evidence: `src/app/useBookmarks.ts`)
- Bookmark state → IndexedDB storage: persists markers (evidence: `src/app/useBookmarks.ts`)
- Reader coordinator → Bookmarks panel: renders bookmarks (evidence: `src/app/components/Reader.tsx`)
- Reader coordinator → Original PDF pane: renders original PDF (evidence: `src/app/components/Reader.tsx`)
- Original PDF pane → IndexedDB storage: loads saved PDF (evidence: `src/app/components/PdfPane.tsx`)
- App shell → Sync client: syncs library (evidence: `src/app/App.tsx`)
- Sync client → IndexedDB storage: applies merged data (evidence: `src/core/sync.ts`)
- Sync client → Sync API: syncs metadata (evidence: `README.md`)
- Sync client → PDF API: transfers PDF (evidence: `README.md`)
