# alexeygrigorev/ai-book-generator architecture

> Architecture diagram of the GitHub repository alexeygrigorev/ai-book-generator, 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/alexeygrigorev/ai-book-generator
- Repository: https://github.com/alexeygrigorev/ai-book-generator

## Overview

AI Book Generator turns a user’s topic and feedback into a structured book plan, generates book content through either section-based or chapter-based execution, and supports audio and publishing outputs. The graph includes README-documented EPUB, KDP, and audio-conversion capabilities even though those implementations were not sampled; their links reflect documented responsibilities, not inspected call details.

Main entry points: [`books`](https://github.com/alexeygrigorev/ai-book-generator/tree/main/books) (Book files), [`ui/streamlit_app.py`](https://github.com/alexeygrigorev/ai-book-generator/blob/main/ui/streamlit_app.py) (Planning UI), [`book_generator/plan.py`](https://github.com/alexeygrigorev/ai-book-generator/blob/main/book_generator/plan.py) (Section planner), [`chapter_based/plan.py`](https://github.com/alexeygrigorev/ai-book-generator/blob/main/chapter_based/plan.py) (Chapter planner)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_planning["Planning"]
  node_ui["Planning UI<br/>[streamlit_app.py]"]
  node_section_plan["Section planner<br/>[plan.py]"]
  node_chapter_plan["Chapter planner<br/>[plan.py]"]
  node_plan_models["Plan models<br/>[models.py]"]
  node_chapter_models["Chapter models<br/>[models.py]"]
end

subgraph group_writing["Book generation"]
  node_book_store[("Book files")]
  node_section_execute["Section writer<br/>[execute.py]"]
  node_chapter_execute["Chapter writer<br/>[execute.py]"]
  node_genai_utils["AI client and costs<br/>[utils.py]"]
end

subgraph group_audio["Audio"]
  node_tts_runner["Audio runner<br/>[run_tts.py]"]
  node_tts["Speech generation<br/>[tts.py]"]
  node_batch_tts["Batch speech<br/>[tts_batch.py]"]
  node_s3[("AWS S3")]
  node_audio_convert["WAV to MP3"]
  node_local_wav[("Local WAV files")]
end

subgraph group_publishing["Publishing"]
  node_ebook["EPUB export"]
  node_interior["KDP interior"]
  node_cover["KDP cover"]
end

node_user(("Book author"))
node_gemini{{"Gemini API"}}

node_user -->|"configures topic"| node_ui
node_ui -->|"streams and refines"| node_section_plan
node_ui -->|"requests plans"| node_gemini
node_ui -->|"saves structured plan"| node_book_store
node_section_plan -->|"generates plan"| node_gemini
node_section_plan -->|"structures plan"| node_plan_models
node_section_plan -->|"writes YAML plan"| node_book_store
node_chapter_plan -->|"generates plan"| node_gemini
node_chapter_plan -->|"structures plan"| node_chapter_models
node_chapter_plan -->|"writes YAML plan"| node_book_store
node_section_execute -->|"reads plan and writes content"| node_book_store
node_section_execute -->|"tracks generation cost"| node_genai_utils
node_chapter_execute -->|"reads plan and writes content"| node_book_store
node_chapter_execute -->|"tracks generation cost"| node_genai_utils
node_genai_utils -->|"creates AI client"| node_gemini
node_tts_runner -->|"runs speech generation"| node_tts
node_tts_runner -->|"reads book markdown"| node_book_store
node_tts -->|"generates audio"| node_gemini
node_tts -.->|"checks and uploads audio"| node_s3
node_batch_tts -->|"reads book markdown"| node_book_store
node_batch_tts -->|"submits batch requests"| node_gemini
node_batch_tts -->|"writes local WAV files"| node_local_wav
node_audio_convert -.->|"converts stored audio"| node_s3
node_ebook -->|"reads book content"| node_book_store
node_interior -->|"reads book content"| node_book_store
node_cover -->|"reads cover inputs"| node_book_store

click node_ui "https://github.com/alexeygrigorev/ai-book-generator/blob/main/ui/streamlit_app.py"
click node_section_plan "https://github.com/alexeygrigorev/ai-book-generator/blob/main/book_generator/plan.py"
click node_chapter_plan "https://github.com/alexeygrigorev/ai-book-generator/blob/main/chapter_based/plan.py"
click node_plan_models "https://github.com/alexeygrigorev/ai-book-generator/blob/main/book_generator/models.py"
click node_chapter_models "https://github.com/alexeygrigorev/ai-book-generator/blob/main/chapter_based/models.py"
click node_book_store "https://github.com/alexeygrigorev/ai-book-generator/tree/main/books"
click node_section_execute "https://github.com/alexeygrigorev/ai-book-generator/blob/main/book_generator/execute.py"
click node_chapter_execute "https://github.com/alexeygrigorev/ai-book-generator/blob/main/chapter_based/execute.py"
click node_genai_utils "https://github.com/alexeygrigorev/ai-book-generator/blob/main/book_generator/utils.py"
click node_tts_runner "https://github.com/alexeygrigorev/ai-book-generator/blob/main/scripts/run_tts.py"
click node_tts "https://github.com/alexeygrigorev/ai-book-generator/blob/main/book_generator/tts.py"
click node_batch_tts "https://github.com/alexeygrigorev/ai-book-generator/blob/main/book_generator/tts_batch.py"
click node_audio_convert "https://github.com/alexeygrigorev/ai-book-generator/blob/main/scripts/convert_wav_to_mp3.py"
click node_ebook "https://github.com/alexeygrigorev/ai-book-generator/blob/main/scripts/convert_to_ebook.py"
click node_interior "https://github.com/alexeygrigorev/ai-book-generator/blob/main/scripts/create_kdp_interior.py"
click node_cover "https://github.com/alexeygrigorev/ai-book-generator/blob/main/scripts/create_kdp_cover.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_ui,node_section_plan,node_chapter_plan,node_plan_models,node_chapter_models toneBlue
class node_book_store,node_section_execute,node_chapter_execute,node_genai_utils toneAmber
class node_tts_runner,node_tts,node_batch_tts,node_s3,node_audio_convert,node_local_wav,node_gemini toneMint
class node_ebook,node_interior,node_cover toneRose
class node_user toneIndigo
```

## Components

### Planning

- [Planning UI](https://github.com/alexeygrigorev/ai-book-generator/blob/main/ui/streamlit_app.py): `ui/streamlit_app.py`
- [Section planner](https://github.com/alexeygrigorev/ai-book-generator/blob/main/book_generator/plan.py): `book_generator/plan.py`
- [Chapter planner](https://github.com/alexeygrigorev/ai-book-generator/blob/main/chapter_based/plan.py): `chapter_based/plan.py`
- [Plan models](https://github.com/alexeygrigorev/ai-book-generator/blob/main/book_generator/models.py): `book_generator/models.py`
- [Chapter models](https://github.com/alexeygrigorev/ai-book-generator/blob/main/chapter_based/models.py): `chapter_based/models.py`

### Book generation

- [Book files](https://github.com/alexeygrigorev/ai-book-generator/tree/main/books): `books`
- [Section writer](https://github.com/alexeygrigorev/ai-book-generator/blob/main/book_generator/execute.py): `book_generator/execute.py`
- [Chapter writer](https://github.com/alexeygrigorev/ai-book-generator/blob/main/chapter_based/execute.py): `chapter_based/execute.py`
- [AI client and costs](https://github.com/alexeygrigorev/ai-book-generator/blob/main/book_generator/utils.py): `book_generator/utils.py`

### Audio

- [Audio runner](https://github.com/alexeygrigorev/ai-book-generator/blob/main/scripts/run_tts.py): `scripts/run_tts.py`
- [Speech generation](https://github.com/alexeygrigorev/ai-book-generator/blob/main/book_generator/tts.py): `book_generator/tts.py`
- [Batch speech](https://github.com/alexeygrigorev/ai-book-generator/blob/main/book_generator/tts_batch.py): `book_generator/tts_batch.py`
- **AWS S3**
- [WAV to MP3](https://github.com/alexeygrigorev/ai-book-generator/blob/main/scripts/convert_wav_to_mp3.py): `scripts/convert_wav_to_mp3.py`
- **Local WAV files**

### Publishing

- [EPUB export](https://github.com/alexeygrigorev/ai-book-generator/blob/main/scripts/convert_to_ebook.py): `scripts/convert_to_ebook.py`
- [KDP interior](https://github.com/alexeygrigorev/ai-book-generator/blob/main/scripts/create_kdp_interior.py): `scripts/create_kdp_interior.py`
- [KDP cover](https://github.com/alexeygrigorev/ai-book-generator/blob/main/scripts/create_kdp_cover.py): `scripts/create_kdp_cover.py`

### Other components

- **Book author**
- **Gemini API**

## Connections

- Book author → Planning UI: configures topic
- Planning UI → Section planner: streams and refines
- Planning UI → Gemini API: requests plans
- Planning UI → Book files: saves structured plan
- Section planner → Gemini API: generates plan
- Section planner → Plan models: structures plan
- Section planner → Book files: writes YAML plan
- Chapter planner → Gemini API: generates plan
- Chapter planner → Chapter models: structures plan
- Chapter planner → Book files: writes YAML plan
- Section writer → Book files: reads plan and writes content
- Section writer → AI client and costs: tracks generation cost
- Chapter writer → Book files: reads plan and writes content
- Chapter writer → AI client and costs: tracks generation cost
- AI client and costs → Gemini API: creates AI client
- Audio runner → Speech generation: runs speech generation
- Audio runner → Book files: reads book markdown
- Speech generation → Gemini API: generates audio
- Speech generation → AWS S3: checks and uploads audio
- Batch speech → Book files: reads book markdown
- Batch speech → Gemini API: submits batch requests
- Batch speech → Local WAV files: writes local WAV files
- WAV to MP3 → AWS S3: converts stored audio
- EPUB export → Book files: reads book content
- KDP interior → Book files: reads book content
- KDP cover → Book files: reads cover inputs
