# dewmith/narruvo architecture

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

- Interactive diagram: https://gitdiagram.com/dewmith/narruvo
- Repository: https://github.com/dewmith/narruvo

## Overview

Narruvo is an offline desktop PDF audiobook reader. A user imports or selects a PDF; the app extracts and prepares page text, presents it in the reader, and turns sections into cached Kokoro speech for playback with synchronized highlighting. The library stores document identity and reading progress, while settings and voice-model setup support local use. The graph emphasizes documented workflow and major README features; several internal modules are indexed but unsampled, so uncertain implementation links are omitted or marked unverified.

Main entry points: [`src/narruvo/ui/main_window.py`](https://github.com/dewmith/narruvo/blob/main/src/narruvo/ui/main_window.py) (Main window), [`src/narruvo/playback.py`](https://github.com/dewmith/narruvo/blob/main/src/narruvo/playback.py) (Playback controller), [`src/narruvo/app.py`](https://github.com/dewmith/narruvo/blob/main/src/narruvo/app.py) (App entry), [`src/narruvo/ui/viewer.py`](https://github.com/dewmith/narruvo/blob/main/src/narruvo/ui/viewer.py) (PDF and text viewer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_shell["Desktop reader"]
  node_app["App entry<br/>[app.py]"]
  node_window["Main window<br/>[main_window.py]"]
  node_library_ui["Library view<br/>[library_view.py]"]
  node_viewer["PDF and text viewer<br/>[viewer.py]"]
  node_playback_ui["Playback controls<br/>[playback_bar.py]"]
  node_theme["Interface theme<br/>[theme.py]"]
end

subgraph group_documents["PDF preparation"]
  node_pdf_service["PDF extraction and rendering<br/>[pdf.py]"]
  node_text_prep["Text preparation<br/>[text.py]"]
  node_documents["Document coordination<br/>[documents.py]"]
  node_workers["Process workers<br/>[workers.py]"]
  node_domain["Shared reading records<br/>[domain.py]"]
end

subgraph group_speech["Narration playback"]
  node_playback["Playback controller<br/>[playback.py]"]
  node_tts["Kokoro synthesis and cache<br/>[tts.py]"]
  node_audio["Audio output<br/>[audio.py]"]
  node_timing["Speech timing alignment<br/>[timing.py]"]
end

subgraph group_local["Local state and setup"]
  node_persistence[("Library and progress store<br/>[persistence.py]")]
  node_config["Settings and paths<br/>[config.py]"]
  node_model_setup["Voice setup UI<br/>[model_setup.py]"]
  node_models["Model download and validation<br/>[models.py]"]
  node_logs["Diagnostic logging<br/>[logging_setup.py]"]
end

node_user(("Reader"))
node_model_files["Kokoro model release"]

node_user -->|"launches"| node_app
node_app -->|"loads paths"| node_config
node_app -->|"configures"| node_logs
node_app -->|"applies"| node_theme
node_app -->|"opens"| node_window
node_user -->|"imports or selects PDF"| node_window
node_window -->|"refreshes"| node_library_ui
node_window -->|"presents document"| node_viewer
node_window -->|"coordinates controls"| node_playback_ui
node_window -.->|"coordinates documents"| node_documents
node_window -->|"saves progress"| node_persistence
node_window -->|"controls narration"| node_playback
node_window -->|"reads preferences"| node_config
node_window -->|"opens setup"| node_model_setup
node_documents -.->|"uses workers"| node_workers
node_workers -->|"dispatches PDF jobs"| node_pdf_service
node_workers -->|"dispatches speech jobs"| node_tts
node_pdf_service -.->|"prepares extracted text"| node_text_prep
node_pdf_service -.->|"provides rendered pages"| node_viewer
node_text_prep -.->|"supplies aligned text"| node_viewer
node_playback -->|"submits synthesis jobs"| node_workers
node_playback -->|"controls output"| node_audio
node_tts -.->|"uses speech timings"| node_timing
node_playback -.->|"updates controls"| node_playback_ui
node_playback -->|"drives highlighting"| node_viewer
node_viewer -->|"shows synchronized reading"| node_user
node_window -.->|"tracks reading state"| node_domain
node_persistence -->|"stores progress records"| node_domain
node_config -.->|"retains preferences"| node_user
node_model_setup -.->|"downloads or selects files"| node_models
node_models -->|"downloads verified assets"| node_model_files
node_model_setup -.->|"initializes voices"| node_playback
node_tts -.->|"loads local models"| node_model_files

click node_app "https://github.com/dewmith/narruvo/blob/main/src/narruvo/app.py"
click node_window "https://github.com/dewmith/narruvo/blob/main/src/narruvo/ui/main_window.py"
click node_library_ui "https://github.com/dewmith/narruvo/blob/main/src/narruvo/ui/library_view.py"
click node_viewer "https://github.com/dewmith/narruvo/blob/main/src/narruvo/ui/viewer.py"
click node_playback_ui "https://github.com/dewmith/narruvo/blob/main/src/narruvo/ui/playback_bar.py"
click node_pdf_service "https://github.com/dewmith/narruvo/blob/main/src/narruvo/pdf.py"
click node_text_prep "https://github.com/dewmith/narruvo/blob/main/src/narruvo/text.py"
click node_documents "https://github.com/dewmith/narruvo/blob/main/src/narruvo/documents.py"
click node_workers "https://github.com/dewmith/narruvo/blob/main/src/narruvo/workers.py"
click node_playback "https://github.com/dewmith/narruvo/blob/main/src/narruvo/playback.py"
click node_tts "https://github.com/dewmith/narruvo/blob/main/src/narruvo/tts.py"
click node_audio "https://github.com/dewmith/narruvo/blob/main/src/narruvo/audio.py"
click node_timing "https://github.com/dewmith/narruvo/blob/main/src/narruvo/timing.py"
click node_domain "https://github.com/dewmith/narruvo/blob/main/src/narruvo/domain.py"
click node_persistence "https://github.com/dewmith/narruvo/blob/main/src/narruvo/persistence.py"
click node_config "https://github.com/dewmith/narruvo/blob/main/src/narruvo/config.py"
click node_model_setup "https://github.com/dewmith/narruvo/blob/main/src/narruvo/ui/model_setup.py"
click node_models "https://github.com/dewmith/narruvo/blob/main/src/narruvo/models.py"
click node_logs "https://github.com/dewmith/narruvo/blob/main/src/narruvo/logging_setup.py"
click node_theme "https://github.com/dewmith/narruvo/blob/main/src/narruvo/ui/theme.py"

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_window,node_library_ui,node_viewer,node_playback_ui,node_theme toneBlue
class node_pdf_service,node_text_prep,node_documents,node_workers,node_domain toneAmber
class node_playback,node_tts,node_audio,node_timing toneMint
class node_persistence,node_config,node_model_setup,node_models,node_logs toneRose
class node_user,node_model_files toneIndigo
```

## Components

### Desktop reader

- [App entry](https://github.com/dewmith/narruvo/blob/main/src/narruvo/app.py): `src/narruvo/app.py`
- [Main window](https://github.com/dewmith/narruvo/blob/main/src/narruvo/ui/main_window.py): `src/narruvo/ui/main_window.py`
- [Library view](https://github.com/dewmith/narruvo/blob/main/src/narruvo/ui/library_view.py): `src/narruvo/ui/library_view.py`
- [PDF and text viewer](https://github.com/dewmith/narruvo/blob/main/src/narruvo/ui/viewer.py): `src/narruvo/ui/viewer.py`
- [Playback controls](https://github.com/dewmith/narruvo/blob/main/src/narruvo/ui/playback_bar.py): `src/narruvo/ui/playback_bar.py`
- [Interface theme](https://github.com/dewmith/narruvo/blob/main/src/narruvo/ui/theme.py): `src/narruvo/ui/theme.py`

### PDF preparation

- [PDF extraction and rendering](https://github.com/dewmith/narruvo/blob/main/src/narruvo/pdf.py): `src/narruvo/pdf.py`
- [Text preparation](https://github.com/dewmith/narruvo/blob/main/src/narruvo/text.py): `src/narruvo/text.py`
- [Document coordination](https://github.com/dewmith/narruvo/blob/main/src/narruvo/documents.py): `src/narruvo/documents.py`
- [Process workers](https://github.com/dewmith/narruvo/blob/main/src/narruvo/workers.py): `src/narruvo/workers.py`
- [Shared reading records](https://github.com/dewmith/narruvo/blob/main/src/narruvo/domain.py): `src/narruvo/domain.py`

### Narration playback

- [Playback controller](https://github.com/dewmith/narruvo/blob/main/src/narruvo/playback.py): `src/narruvo/playback.py`
- [Kokoro synthesis and cache](https://github.com/dewmith/narruvo/blob/main/src/narruvo/tts.py): `src/narruvo/tts.py`
- [Audio output](https://github.com/dewmith/narruvo/blob/main/src/narruvo/audio.py): `src/narruvo/audio.py`
- [Speech timing alignment](https://github.com/dewmith/narruvo/blob/main/src/narruvo/timing.py): `src/narruvo/timing.py`

### Local state and setup

- [Library and progress store](https://github.com/dewmith/narruvo/blob/main/src/narruvo/persistence.py): `src/narruvo/persistence.py`
- [Settings and paths](https://github.com/dewmith/narruvo/blob/main/src/narruvo/config.py): `src/narruvo/config.py`
- [Voice setup UI](https://github.com/dewmith/narruvo/blob/main/src/narruvo/ui/model_setup.py): `src/narruvo/ui/model_setup.py`
- [Model download and validation](https://github.com/dewmith/narruvo/blob/main/src/narruvo/models.py): `src/narruvo/models.py`
- [Diagnostic logging](https://github.com/dewmith/narruvo/blob/main/src/narruvo/logging_setup.py): `src/narruvo/logging_setup.py`

### Other components

- **Reader**
- **Kokoro model release**

## Connections

- Reader → App entry: launches (evidence: `src/narruvo/app.py`)
- App entry → Settings and paths: loads paths (evidence: `src/narruvo/app.py`)
- App entry → Diagnostic logging: configures (evidence: `src/narruvo/app.py`)
- App entry → Interface theme: applies (evidence: `src/narruvo/app.py`)
- App entry → Main window: opens (evidence: `src/narruvo/app.py`)
- Reader → Main window: imports or selects PDF (evidence: `README.md`)
- Main window → Library view: refreshes (evidence: `src/narruvo/ui/main_window.py`)
- Main window → PDF and text viewer: presents document (evidence: `src/narruvo/ui/main_window.py`)
- Main window → Playback controls: coordinates controls (evidence: `src/narruvo/ui/main_window.py`)
- Main window → Document coordination: coordinates documents (evidence: `src/narruvo/ui/main_window.py`)
- Main window → Library and progress store: saves progress (evidence: `src/narruvo/ui/main_window.py`)
- Main window → Playback controller: controls narration (evidence: `src/narruvo/ui/main_window.py`)
- Main window → Settings and paths: reads preferences (evidence: `src/narruvo/ui/main_window.py`)
- Main window → Voice setup UI: opens setup (evidence: `src/narruvo/ui/main_window.py`)
- Document coordination → Process workers: uses workers (evidence: `src/narruvo/documents.py`)
- Process workers → PDF extraction and rendering: dispatches PDF jobs (evidence: `src/narruvo/workers.py`)
- Process workers → Kokoro synthesis and cache: dispatches speech jobs (evidence: `src/narruvo/workers.py`)
- PDF extraction and rendering → Text preparation: prepares extracted text (evidence: `src/narruvo/pdf.py`)
- PDF extraction and rendering → PDF and text viewer: provides rendered pages (evidence: `src/narruvo/ui/viewer.py`)
- Text preparation → PDF and text viewer: supplies aligned text
- Playback controller → Process workers: submits synthesis jobs (evidence: `src/narruvo/playback.py`)
- Playback controller → Audio output: controls output (evidence: `src/narruvo/playback.py`)
- Kokoro synthesis and cache → Speech timing alignment: uses speech timings (evidence: `src/narruvo/tts.py`)
- Playback controller → Playback controls: updates controls
- Playback controller → PDF and text viewer: drives highlighting (evidence: `README.md`)
- PDF and text viewer → Reader: shows synchronized reading (evidence: `README.md`)
- Main window → Shared reading records: tracks reading state (evidence: `src/narruvo/ui/main_window.py`)
- Library and progress store → Shared reading records: stores progress records (evidence: `src/narruvo/persistence.py`)
- Settings and paths → Reader: retains preferences
- Voice setup UI → Model download and validation: downloads or selects files (evidence: `src/narruvo/ui/model_setup.py`)
- Model download and validation → Kokoro model release: downloads verified assets (evidence: `README.md`)
- Voice setup UI → Playback controller: initializes voices
- Kokoro synthesis and cache → Kokoro model release: loads local models
