# denizsafak/abogen architecture

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

- Interactive diagram: https://gitdiagram.com/denizsafak/abogen
- Repository: https://github.com/denizsafak/abogen

## Overview

Abogen converts books and other text sources into spoken audio with synchronized subtitles. Users submit work through either the desktop GUI or the feature-richer Web UI; inputs are extracted, prepared for conversion, synthesized by a selected TTS backend, and written as audio and subtitle outputs. The repository also supports chapter and speaker/entity workflows, plugin-based engines, LLM normalization, and Audiobookshelf/Calibre integrations. The graph combines README capabilities with the sampled source; links for unsampled subsystems are limited to documented or evident entry points.

Main entry points: [`abogen/application/conversion_service.py`](https://github.com/denizsafak/abogen/blob/main/abogen/application/conversion_service.py) (Conversion service), [`abogen/application/conversion_executor.py`](https://github.com/denizsafak/abogen/blob/main/abogen/application/conversion_executor.py) (Conversion executor), [`abogen/webui/app.py`](https://github.com/denizsafak/abogen/blob/main/abogen/webui/app.py) (Web UI), [`abogen/pyqt/main.py`](https://github.com/denizsafak/abogen/blob/main/abogen/pyqt/main.py) (Desktop GUI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User interfaces"]
  node_desktop["Desktop GUI<br/>[main.py]"]
  node_web["Web UI<br/>[app.py]"]
  node_web_routes["Wizard routes<br/>[main.py]"]
  node_queue["Conversion queue"]
end

subgraph group_preparation["Input preparation"]
  node_extract["Text extraction<br/>[text_extractor.py]"]
  node_book_parse["Book parsing<br/>[book_parser.py]"]
  node_chapter_select["Chapter selection"]
  node_entity_analysis["Speaker analysis"]
  node_voice_resolve["Voice resolution<br/>[voice_resolver.py]"]
  node_normalization["Text normalization<br/>[normalization.py]"]
  node_llm["LLM service<br/>[llm_client.py]"]
end

subgraph group_conversion["Conversion runtime"]
  node_conversion_service["Conversion service"]
  node_executor["Conversion executor"]
  node_pipeline_factory["Pipeline factory"]
  node_emission["TTS emission"]
  node_kokoro["Kokoro engine<br/>[engine.py]"]
  node_supertonic["Supertonic engine<br/>[engine.py]"]
end

subgraph group_outputs["Output and integrations"]
  node_audio_sink["Audio output<br/>[audio_sink.py]"]
  node_subtitles["Subtitle generation"]
  node_export["EPUB export<br/>[exporter.py]"]
  node_audiobookshelf["Audiobookshelf<br/>[audiobookshelf.py]"]
  node_calibre["Calibre OPDS<br/>[calibre_opds.py]"]
end

node_user(("User"))
node_llm_service(("LLM endpoint"))

node_user -->|"submits work"| node_desktop
node_user -->|"submits work"| node_web
node_desktop -->|"queues jobs"| node_queue
node_desktop -->|"requests conversion"| node_conversion_service
node_web -->|"serves wizard"| node_web_routes
node_web_routes -->|"extracts upload"| node_extract
node_web_routes -->|"creates job"| node_conversion_service
node_extract -->|"parses books"| node_book_parse
node_conversion_service -->|"selects chapters"| node_chapter_select
node_conversion_service -->|"analyzes speakers"| node_entity_analysis
node_conversion_service -->|"resolves voices"| node_voice_resolve
node_conversion_service -->|"executes job"| node_executor
node_executor -->|"normalizes text"| node_normalization
node_normalization -.->|"requests normalization"| node_llm
node_llm -.->|"sends prompts"| node_llm_service
node_executor -->|"gets pipeline"| node_pipeline_factory
node_executor -->|"emits segments"| node_emission
node_pipeline_factory -->|"creates engine"| node_kokoro
node_pipeline_factory -->|"creates engine"| node_supertonic
node_emission -->|"writes audio"| node_audio_sink
node_executor -->|"processes tokens"| node_subtitles
node_conversion_service -.->|"exports EPUB"| node_export
node_web -.->|"integrates library"| node_audiobookshelf
node_web -.->|"uses OPDS"| node_calibre

click node_desktop "https://github.com/denizsafak/abogen/blob/main/abogen/pyqt/main.py"
click node_web "https://github.com/denizsafak/abogen/blob/main/abogen/webui/app.py"
click node_web_routes "https://github.com/denizsafak/abogen/blob/main/abogen/webui/routes/main.py"
click node_queue "https://github.com/denizsafak/abogen/blob/main/abogen/pyqt/queue_manager_gui.py"
click node_conversion_service "https://github.com/denizsafak/abogen/blob/main/abogen/application/conversion_service.py"
click node_extract "https://github.com/denizsafak/abogen/blob/main/abogen/text_extractor.py"
click node_book_parse "https://github.com/denizsafak/abogen/blob/main/abogen/book_parser.py"
click node_chapter_select "https://github.com/denizsafak/abogen/blob/main/abogen/application/chapter_selection.py"
click node_entity_analysis "https://github.com/denizsafak/abogen/blob/main/abogen/speaker_analysis.py"
click node_voice_resolve "https://github.com/denizsafak/abogen/blob/main/abogen/application/voice_resolver.py"
click node_normalization "https://github.com/denizsafak/abogen/blob/main/abogen/domain/normalization.py"
click node_llm "https://github.com/denizsafak/abogen/blob/main/abogen/llm_client.py"
click node_executor "https://github.com/denizsafak/abogen/blob/main/abogen/application/conversion_executor.py"
click node_pipeline_factory "https://github.com/denizsafak/abogen/blob/main/abogen/domain/pipeline_factory.py"
click node_emission "https://github.com/denizsafak/abogen/blob/main/abogen/domain/conversion_pipeline.py"
click node_kokoro "https://github.com/denizsafak/abogen/blob/main/plugins/kokoro/engine.py"
click node_supertonic "https://github.com/denizsafak/abogen/blob/main/plugins/supertonic/engine.py"
click node_audio_sink "https://github.com/denizsafak/abogen/blob/main/abogen/domain/audio_sink.py"
click node_subtitles "https://github.com/denizsafak/abogen/blob/main/abogen/domain/subtitle_generation.py"
click node_export "https://github.com/denizsafak/abogen/blob/main/abogen/epub3/exporter.py"
click node_audiobookshelf "https://github.com/denizsafak/abogen/blob/main/abogen/integrations/audiobookshelf.py"
click node_calibre "https://github.com/denizsafak/abogen/blob/main/abogen/integrations/calibre_opds.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_desktop,node_web,node_web_routes,node_queue,node_user toneBlue
class node_extract,node_book_parse,node_chapter_select,node_entity_analysis,node_voice_resolve,node_normalization,node_llm toneAmber
class node_conversion_service,node_executor,node_pipeline_factory,node_emission,node_kokoro,node_supertonic toneMint
class node_audio_sink,node_subtitles,node_export,node_audiobookshelf,node_calibre toneRose
class node_llm_service toneIndigo
```

## Components

### User interfaces

- [Desktop GUI](https://github.com/denizsafak/abogen/blob/main/abogen/pyqt/main.py): `abogen/pyqt/main.py`
- [Web UI](https://github.com/denizsafak/abogen/blob/main/abogen/webui/app.py): `abogen/webui/app.py`
- [Wizard routes](https://github.com/denizsafak/abogen/blob/main/abogen/webui/routes/main.py): `abogen/webui/routes/main.py`
- [Conversion queue](https://github.com/denizsafak/abogen/blob/main/abogen/pyqt/queue_manager_gui.py): `abogen/pyqt/queue_manager_gui.py`

### Input preparation

- [Text extraction](https://github.com/denizsafak/abogen/blob/main/abogen/text_extractor.py): `abogen/text_extractor.py`
- [Book parsing](https://github.com/denizsafak/abogen/blob/main/abogen/book_parser.py): `abogen/book_parser.py`
- [Chapter selection](https://github.com/denizsafak/abogen/blob/main/abogen/application/chapter_selection.py): `abogen/application/chapter_selection.py`
- [Speaker analysis](https://github.com/denizsafak/abogen/blob/main/abogen/speaker_analysis.py): `abogen/speaker_analysis.py`
- [Voice resolution](https://github.com/denizsafak/abogen/blob/main/abogen/application/voice_resolver.py): `abogen/application/voice_resolver.py`
- [Text normalization](https://github.com/denizsafak/abogen/blob/main/abogen/domain/normalization.py): `abogen/domain/normalization.py`
- [LLM service](https://github.com/denizsafak/abogen/blob/main/abogen/llm_client.py): `abogen/llm_client.py`

### Conversion runtime

- [Conversion service](https://github.com/denizsafak/abogen/blob/main/abogen/application/conversion_service.py): `abogen/application/conversion_service.py`
- [Conversion executor](https://github.com/denizsafak/abogen/blob/main/abogen/application/conversion_executor.py): `abogen/application/conversion_executor.py`
- [Pipeline factory](https://github.com/denizsafak/abogen/blob/main/abogen/domain/pipeline_factory.py): `abogen/domain/pipeline_factory.py`
- [TTS emission](https://github.com/denizsafak/abogen/blob/main/abogen/domain/conversion_pipeline.py): `abogen/domain/conversion_pipeline.py`
- [Kokoro engine](https://github.com/denizsafak/abogen/blob/main/plugins/kokoro/engine.py): `plugins/kokoro/engine.py`
- [Supertonic engine](https://github.com/denizsafak/abogen/blob/main/plugins/supertonic/engine.py): `plugins/supertonic/engine.py`

### Output and integrations

- [Audio output](https://github.com/denizsafak/abogen/blob/main/abogen/domain/audio_sink.py): `abogen/domain/audio_sink.py`
- [Subtitle generation](https://github.com/denizsafak/abogen/blob/main/abogen/domain/subtitle_generation.py): `abogen/domain/subtitle_generation.py`
- [EPUB export](https://github.com/denizsafak/abogen/blob/main/abogen/epub3/exporter.py): `abogen/epub3/exporter.py`
- [Audiobookshelf](https://github.com/denizsafak/abogen/blob/main/abogen/integrations/audiobookshelf.py): `abogen/integrations/audiobookshelf.py`
- [Calibre OPDS](https://github.com/denizsafak/abogen/blob/main/abogen/integrations/calibre_opds.py): `abogen/integrations/calibre_opds.py`

### Other components

- **User**
- **LLM endpoint**

## Connections

- User → Desktop GUI: submits work
- User → Web UI: submits work
- Desktop GUI → Conversion queue: queues jobs
- Desktop GUI → Conversion service: requests conversion
- Web UI → Wizard routes: serves wizard
- Wizard routes → Text extraction: extracts upload
- Wizard routes → Conversion service: creates job
- Text extraction → Book parsing: parses books
- Conversion service → Chapter selection: selects chapters
- Conversion service → Speaker analysis: analyzes speakers
- Conversion service → Voice resolution: resolves voices
- Conversion service → Conversion executor: executes job
- Conversion executor → Text normalization: normalizes text
- Text normalization → LLM service: requests normalization
- LLM service → LLM endpoint: sends prompts
- Conversion executor → Pipeline factory: gets pipeline
- Conversion executor → TTS emission: emits segments
- Pipeline factory → Kokoro engine: creates engine
- Pipeline factory → Supertonic engine: creates engine
- TTS emission → Audio output: writes audio
- Conversion executor → Subtitle generation: processes tokens
- Conversion service → EPUB export: exports EPUB
- Web UI → Audiobookshelf: integrates library
- Web UI → Calibre OPDS: uses OPDS