# samubraila/buch architecture

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

- Interactive diagram: https://gitdiagram.com/samubraila/buch
- Repository: https://github.com/samubraila/buch

## Overview

LeseWelt is a local-first reading and language-learning web app. Users import or discover a book, read it with word lookup and translation, and can listen, save vocabulary, or train on saved words; a separate audiobook player handles LibriVox recordings. The graph also preserves statistics, settings, backup, and update capabilities documented in the README. Most module connections are supported by the SOURCE INDEX reference lists; unsampled implementation details are not expanded into speculative flows.

Main entry points: [`js/popup.js`](https://github.com/samubraila/buch/blob/main/js/popup.js) (Word lookup), [`js/db.js`](https://github.com/samubraila/buch/blob/main/js/db.js) (IndexedDB), [`js/catalog.js`](https://github.com/samubraila/buch/blob/main/js/catalog.js) (Book discovery), [`js/audioPlayer.js`](https://github.com/samubraila/buch/blob/main/js/audioPlayer.js) (Audiobook player)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App shell"]
  node_library["Library<br/>[library.js]"]
  node_catalog["Book discovery<br/>[catalog.js]"]
  node_catalogdata["Catalog data<br/>[catalogData.js]"]
  node_settings["Settings<br/>[settings.js]"]
  node_updates["App updates<br/>[update.js]"]
end

subgraph group_reading["Reading and audio"]
  node_reader["Reader<br/>[reader.js]"]
  node_importer["Book importer<br/>[importer.js]"]
  node_parsers["Format parsers"]
  node_listen["Read-aloud player<br/>[listen.js]"]
  node_listenengine["Read-aloud engine<br/>[listenEngine.js]"]
  node_audiobooks["Audiobook player<br/>[audioPlayer.js]"]
end

subgraph group_learning["Language learning"]
  node_lookup["Word lookup<br/>[popup.js]"]
  node_translation["Translation<br/>[translate.js]"]
  node_dictionary["Dictionary and grammar<br/>[grammar.js]"]
  node_pronunciation["Speech<br/>[speech.js]"]
  node_practice["Pronunciation practice<br/>[practice.js]"]
  node_vocab["Vocabulary book<br/>[vocab.js]"]
  node_training["Vocabulary training<br/>[train.js]"]
end

subgraph group_data["Local data and support"]
  node_vocabstore[("Vocabulary store<br/>[vocabStore.js]")]
  node_stats["Statistics and achievements<br/>[stats.js]"]
  node_achievements["Achievements<br/>[achievements.js]"]
  node_backup["Backup and transfer<br/>[backup.js]"]
  node_database[("IndexedDB<br/>[db.js]")]
end

node_user(("Reader"))
node_translationservices["Translation services"]
node_dictionaryservices["Dictionary services"]
node_bookservices["Book catalogs"]
node_librivox["LibriVox"]
node_browser["Browser speech APIs"]

node_user -->|"opens"| node_library
node_library -->|"imports books"| node_importer
node_importer -->|"parses formats"| node_parsers
node_library -->|"loads books"| node_database
node_user -->|"discovers books"| node_catalog
node_catalog -->|"reads catalog"| node_catalogdata
node_catalog -->|"loads selected book"| node_importer
node_catalog -->|"opens recordings"| node_audiobooks
node_catalog -.->|"searches books"| node_bookservices
node_user -->|"reads"| node_reader
node_reader -->|"loads book content"| node_database
node_reader -->|"opens word card"| node_lookup
node_lookup -->|"translates words"| node_translation
node_lookup -->|"loads word details"| node_dictionary
node_lookup -->|"plays pronunciation"| node_pronunciation
node_lookup -->|"checks spoken word"| node_practice
node_lookup -->|"saves vocabulary"| node_vocabstore
node_translation -->|"requests translation"| node_translationservices
node_dictionary -->|"looks up entries"| node_dictionaryservices
node_pronunciation -->|"uses device speech"| node_browser
node_user -->|"starts read-aloud"| node_listen
node_listen -->|"controls playback"| node_listenengine
node_listenengine -->|"loads book content"| node_database
node_listenengine -->|"translates sentences"| node_translation
node_listenengine -->|"stops conflicting playback"| node_audiobooks
node_user -->|"plays audiobook"| node_audiobooks
node_audiobooks -->|"stores position"| node_database
node_audiobooks -->|"plays recordings"| node_librivox
node_user -->|"reviews words"| node_vocab
node_vocab -->|"reads and edits"| node_vocabstore
node_user -->|"trains vocabulary"| node_training
node_training -->|"reviews due words"| node_vocabstore
node_user -->|"views progress"| node_stats
node_stats -->|"shows achievements"| node_achievements
node_achievements -->|"reads progress data"| node_database
node_user -->|"transfers data"| node_backup
node_backup -->|"exports and imports data"| node_database
node_user -->|"configures app"| node_settings
node_settings -->|"persists preferences"| node_database
node_user -->|"receives updates"| node_updates

click node_reader "https://github.com/samubraila/buch/blob/main/js/reader.js"
click node_library "https://github.com/samubraila/buch/blob/main/js/library.js"
click node_importer "https://github.com/samubraila/buch/blob/main/js/importer.js"
click node_parsers "https://github.com/samubraila/buch/tree/main/js/parsers"
click node_catalog "https://github.com/samubraila/buch/blob/main/js/catalog.js"
click node_catalogdata "https://github.com/samubraila/buch/blob/main/js/catalogData.js"
click node_lookup "https://github.com/samubraila/buch/blob/main/js/popup.js"
click node_translation "https://github.com/samubraila/buch/blob/main/js/translate.js"
click node_dictionary "https://github.com/samubraila/buch/blob/main/js/grammar.js"
click node_pronunciation "https://github.com/samubraila/buch/blob/main/js/speech.js"
click node_practice "https://github.com/samubraila/buch/blob/main/js/practice.js"
click node_vocab "https://github.com/samubraila/buch/blob/main/js/vocab.js"
click node_training "https://github.com/samubraila/buch/blob/main/js/train.js"
click node_vocabstore "https://github.com/samubraila/buch/blob/main/js/vocabStore.js"
click node_listen "https://github.com/samubraila/buch/blob/main/js/listen.js"
click node_listenengine "https://github.com/samubraila/buch/blob/main/js/listenEngine.js"
click node_audiobooks "https://github.com/samubraila/buch/blob/main/js/audioPlayer.js"
click node_stats "https://github.com/samubraila/buch/blob/main/js/stats.js"
click node_achievements "https://github.com/samubraila/buch/blob/main/js/achievements.js"
click node_backup "https://github.com/samubraila/buch/blob/main/js/backup.js"
click node_settings "https://github.com/samubraila/buch/blob/main/js/settings.js"
click node_updates "https://github.com/samubraila/buch/blob/main/js/update.js"
click node_database "https://github.com/samubraila/buch/blob/main/js/db.js"

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_library,node_catalog,node_catalogdata,node_settings,node_updates,node_browser toneBlue
class node_reader,node_importer,node_parsers,node_listen,node_listenengine,node_audiobooks toneAmber
class node_lookup,node_translation,node_dictionary,node_pronunciation,node_practice,node_vocab,node_training toneMint
class node_vocabstore,node_stats,node_achievements,node_backup,node_database toneRose
class node_user,node_translationservices,node_dictionaryservices,node_bookservices,node_librivox toneIndigo
```

## Components

### App shell

- [Library](https://github.com/samubraila/buch/blob/main/js/library.js): `js/library.js`
- [Book discovery](https://github.com/samubraila/buch/blob/main/js/catalog.js): `js/catalog.js`
- [Catalog data](https://github.com/samubraila/buch/blob/main/js/catalogData.js): `js/catalogData.js`
- [Settings](https://github.com/samubraila/buch/blob/main/js/settings.js): `js/settings.js`
- [App updates](https://github.com/samubraila/buch/blob/main/js/update.js): `js/update.js`

### Reading and audio

- [Reader](https://github.com/samubraila/buch/blob/main/js/reader.js): `js/reader.js`
- [Book importer](https://github.com/samubraila/buch/blob/main/js/importer.js): `js/importer.js`
- [Format parsers](https://github.com/samubraila/buch/tree/main/js/parsers): `js/parsers`
- [Read-aloud player](https://github.com/samubraila/buch/blob/main/js/listen.js): `js/listen.js`
- [Read-aloud engine](https://github.com/samubraila/buch/blob/main/js/listenEngine.js): `js/listenEngine.js`
- [Audiobook player](https://github.com/samubraila/buch/blob/main/js/audioPlayer.js): `js/audioPlayer.js`

### Language learning

- [Word lookup](https://github.com/samubraila/buch/blob/main/js/popup.js): `js/popup.js`
- [Translation](https://github.com/samubraila/buch/blob/main/js/translate.js): `js/translate.js`
- [Dictionary and grammar](https://github.com/samubraila/buch/blob/main/js/grammar.js): `js/grammar.js`
- [Speech](https://github.com/samubraila/buch/blob/main/js/speech.js): `js/speech.js`
- [Pronunciation practice](https://github.com/samubraila/buch/blob/main/js/practice.js): `js/practice.js`
- [Vocabulary book](https://github.com/samubraila/buch/blob/main/js/vocab.js): `js/vocab.js`
- [Vocabulary training](https://github.com/samubraila/buch/blob/main/js/train.js): `js/train.js`

### Local data and support

- [Vocabulary store](https://github.com/samubraila/buch/blob/main/js/vocabStore.js): `js/vocabStore.js`
- [Statistics and achievements](https://github.com/samubraila/buch/blob/main/js/stats.js): `js/stats.js`
- [Achievements](https://github.com/samubraila/buch/blob/main/js/achievements.js): `js/achievements.js`
- [Backup and transfer](https://github.com/samubraila/buch/blob/main/js/backup.js): `js/backup.js`
- [IndexedDB](https://github.com/samubraila/buch/blob/main/js/db.js): `js/db.js`

### Other components

- **Reader**
- **Translation services**
- **Dictionary services**
- **Book catalogs**
- **LibriVox**
- **Browser speech APIs**

## Connections

- Reader → Library: opens (evidence: `README.md`)
- Library → Book importer: imports books (evidence: `js/library.js`)
- Book importer → Format parsers: parses formats (evidence: `js/importer.js`)
- Library → IndexedDB: loads books (evidence: `js/library.js`)
- Reader → Book discovery: discovers books (evidence: `README.md`)
- Book discovery → Catalog data: reads catalog (evidence: `js/catalog.js`)
- Book discovery → Book importer: loads selected book (evidence: `js/catalog.js`)
- Book discovery → Audiobook player: opens recordings (evidence: `js/catalog.js`)
- Book discovery → Book catalogs: searches books (evidence: `README.md`)
- Reader → Reader: reads (evidence: `README.md`)
- Reader → IndexedDB: loads book content (evidence: `js/reader.js`)
- Reader → Word lookup: opens word card (evidence: `js/reader.js`)
- Word lookup → Translation: translates words (evidence: `js/popup.js`)
- Word lookup → Dictionary and grammar: loads word details (evidence: `js/popup.js`)
- Word lookup → Speech: plays pronunciation (evidence: `js/popup.js`)
- Word lookup → Pronunciation practice: checks spoken word (evidence: `js/popup.js`)
- Word lookup → Vocabulary store: saves vocabulary (evidence: `js/popup.js`)
- Translation → Translation services: requests translation (evidence: `README.md`)
- Dictionary and grammar → Dictionary services: looks up entries (evidence: `README.md`)
- Speech → Browser speech APIs: uses device speech (evidence: `README.md`)
- Reader → Read-aloud player: starts read-aloud (evidence: `README.md`)
- Read-aloud player → Read-aloud engine: controls playback (evidence: `js/listen.js`)
- Read-aloud engine → IndexedDB: loads book content (evidence: `js/listenEngine.js`)
- Read-aloud engine → Translation: translates sentences (evidence: `js/listenEngine.js`)
- Read-aloud engine → Audiobook player: stops conflicting playback (evidence: `js/listenEngine.js`)
- Reader → Audiobook player: plays audiobook (evidence: `README.md`)
- Audiobook player → IndexedDB: stores position (evidence: `js/audioPlayer.js`)
- Audiobook player → LibriVox: plays recordings (evidence: `README.md`)
- Reader → Vocabulary book: reviews words (evidence: `README.md`)
- Vocabulary book → Vocabulary store: reads and edits (evidence: `js/vocab.js`)
- Reader → Vocabulary training: trains vocabulary (evidence: `README.md`)
- Vocabulary training → Vocabulary store: reviews due words (evidence: `js/train.js`)
- Reader → Statistics and achievements: views progress (evidence: `README.md`)
- Statistics and achievements → Achievements: shows achievements (evidence: `js/stats.js`)
- Achievements → IndexedDB: reads progress data (evidence: `js/achievements.js`)
- Reader → Backup and transfer: transfers data (evidence: `README.md`)
- Backup and transfer → IndexedDB: exports and imports data (evidence: `js/backup.js`)
- Reader → Settings: configures app (evidence: `README.md`)
- Settings → IndexedDB: persists preferences (evidence: `js/settings.js`)
- Reader → App updates: receives updates (evidence: `README.md`)
