# jdjchelp-jpg/nodebpm4b architecture

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

- Interactive diagram: https://gitdiagram.com/jdjchelp-jpg/nodebpm4b
- Repository: https://github.com/jdjchelp-jpg/nodebpm4b

## Overview

BPM4B is a multimedia and audiobook conversion suite with Node.js and Python interfaces. The main user workflow is submitting audio or a document through the CLI or web interface, then converting it into an audiobook or another supported format. The Node.js application also supports document-to-EPUB, EPUB-to-audiobook, narration, and metadata features; the Python application provides audio processing and M4B encoding. The graph reflects documented capabilities and indexed module references; some subsystem details and call relationships are not visible in the excerpts, so those links are omitted.

Main entry points: [`lib/server.js`](https://github.com/jdjchelp-jpg/nodebpm4b/blob/master/lib/server.js) (Web API), [`bpm4b/main.py`](https://github.com/jdjchelp-jpg/nodebpm4b/blob/master/bpm4b/main.py) (Python application), [`bpm4b/core.py`](https://github.com/jdjchelp-jpg/nodebpm4b/blob/master/bpm4b/core.py) (Python conversion core), [`lib/epub-to-audiobook.js`](https://github.com/jdjchelp-jpg/nodebpm4b/blob/master/lib/epub-to-audiobook.js) (EPUB audiobook)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User interfaces"]
  node_nodecli["Node CLI<br/>[bpm4b.js]"]
  node_web["Web API<br/>[server.js]"]
  node_api["Serverless API<br/>[index.js]"]
  node_colab["Colab tunnels<br/>[colab-support.js]"]
  node_portableserver["Portable web API<br/>[server.js]"]
end

subgraph group_audio["Audio conversion"]
  node_core["Audio operations<br/>[core.js]"]
  node_chapterdetect["Chapter detection"]
  node_portablecore["Portable audio operations<br/>[core.js]"]
end

subgraph group_narration["Narration"]
  node_builder["Audiobook builder"]
  node_tts["Speech synthesis<br/>[tts-engine.js]"]
  node_pool["TTS worker pool<br/>[tts-pool.js]"]
  node_worker["TTS worker<br/>[tts-worker.js]"]
  node_ai["AI planning<br/>[ai-engine.js]"]
  node_abogen["Abogen integration"]
  node_portablebuilder["Portable audiobook builder"]
  node_portabletts["Portable speech synthesis<br/>[tts-engine.js]"]
  node_portableai["Portable AI planning<br/>[ai-engine.js]"]
end

subgraph group_documents["Document conversion"]
  node_docparser["Document parser<br/>[document-parser.js]"]
  node_doc2epub["Document to EPUB"]
  node_epubparser["EPUB parser<br/>[epub-parser.js]"]
  node_epub2audio["EPUB audiobook"]
  node_voices["Language voices"]
end

subgraph group_python["Python processing"]
  node_pycli["Python CLI<br/>[cli.py]"]
  node_pyapp["Python application<br/>[main.py]"]
  node_pycore["Python conversion core<br/>[core.py]"]
  node_encoder["Audio encoder<br/>[encoder.py]"]
  node_pychapters["Chapter generator<br/>[chapters.py]"]
  node_metadata["Metadata tools<br/>[metadata.py]"]
  node_noise["Noise reduction<br/>[noise.py]"]
  node_quality["Quality assurance<br/>[quality.py]"]
  node_pipeline["Parallel pipeline<br/>[pipeline.py]"]
  node_config["Configuration<br/>[config.py]"]
end

node_user(("User"))
node_openrouter["OpenRouter"]

node_user -->|"runs command"| node_nodecli
node_user -->|"uses interface"| node_web
node_nodecli -->|"invokes conversion"| node_core
node_nodecli -->|"starts web"| node_web
node_web -->|"routes audio jobs"| node_core
node_web -->|"routes audiobook jobs"| node_builder
node_web -->|"routes document conversion"| node_doc2epub
node_web -->|"routes EPUB conversion"| node_epub2audio
node_web -->|"uses narration analysis"| node_ai
node_web -->|"configures tunnels"| node_colab
node_api -->|"uses audio operations"| node_core
node_builder -->|"parses documents"| node_docparser
node_builder -->|"detects chapters"| node_chapterdetect
node_builder -->|"generates speech"| node_tts
node_tts -->|"submits synthesis"| node_pool
node_pool -.->|"dispatches chunks"| node_worker
node_ai -->|"requests analysis"| node_openrouter
node_epub2audio -->|"parses EPUB"| node_epubparser
node_epub2audio -->|"selects voices"| node_voices
node_epub2audio -->|"synthesizes chapters"| node_tts
node_epub2audio -->|"supports engine"| node_abogen
node_doc2epub -->|"uses EPUB parsing"| node_epubparser
node_user -->|"runs command"| node_pycli
node_pycli -.->|"starts processing"| node_pyapp
node_pyapp -->|"encodes audio"| node_encoder
node_pyapp -->|"reduces noise"| node_noise
node_pyapp -->|"generates chapters"| node_pychapters
node_pyapp -->|"aggregates metadata"| node_metadata
node_pyapp -->|"runs pipeline"| node_pipeline
node_pyapp -->|"checks quality"| node_quality
node_pycore -->|"uses encoder"| node_encoder
node_pycore -->|"uses chapters"| node_pychapters
node_pycore -->|"uses noise tools"| node_noise
node_pycore -->|"uses metadata"| node_metadata
node_pycore -->|"uses quality checks"| node_quality
node_pipeline -->|"runs encoding"| node_encoder
node_portablecore -.->|"produces conversions"| node_user
node_portableserver -.->|"routes audio jobs"| node_portablecore
node_portableserver -.->|"routes audiobook jobs"| node_portablebuilder
node_portablebuilder -.->|"uses synthesis"| node_portabletts
node_portableserver -.->|"uses AI features"| node_portableai

click node_nodecli "https://github.com/jdjchelp-jpg/nodebpm4b/blob/master/bin/bpm4b.js"
click node_web "https://github.com/jdjchelp-jpg/nodebpm4b/blob/master/lib/server.js"
click node_api "https://github.com/jdjchelp-jpg/nodebpm4b/blob/master/api/index.js"
click node_core "https://github.com/jdjchelp-jpg/nodebpm4b/blob/master/lib/core.js"
click node_chapterdetect "https://github.com/jdjchelp-jpg/nodebpm4b/blob/master/lib/chapter-detector.js"
click node_builder "https://github.com/jdjchelp-jpg/nodebpm4b/blob/master/lib/audiobook-builder.js"
click node_tts "https://github.com/jdjchelp-jpg/nodebpm4b/blob/master/lib/tts-engine.js"
click node_pool "https://github.com/jdjchelp-jpg/nodebpm4b/blob/master/lib/tts-pool.js"
click node_worker "https://github.com/jdjchelp-jpg/nodebpm4b/blob/master/lib/tts-worker.js"
click node_ai "https://github.com/jdjchelp-jpg/nodebpm4b/blob/master/lib/ai-engine.js"
click node_abogen "https://github.com/jdjchelp-jpg/nodebpm4b/blob/master/lib/abogen-integration.js"
click node_docparser "https://github.com/jdjchelp-jpg/nodebpm4b/blob/master/lib/document-parser.js"
click node_doc2epub "https://github.com/jdjchelp-jpg/nodebpm4b/blob/master/lib/document-to-epub.js"
click node_epubparser "https://github.com/jdjchelp-jpg/nodebpm4b/blob/master/lib/epub-parser.js"
click node_epub2audio "https://github.com/jdjchelp-jpg/nodebpm4b/blob/master/lib/epub-to-audiobook.js"
click node_voices "https://github.com/jdjchelp-jpg/nodebpm4b/blob/master/lib/multi-language-voices.js"
click node_colab "https://github.com/jdjchelp-jpg/nodebpm4b/blob/master/lib/colab-support.js"
click node_pycli "https://github.com/jdjchelp-jpg/nodebpm4b/blob/master/bpm4b/cli.py"
click node_pyapp "https://github.com/jdjchelp-jpg/nodebpm4b/blob/master/bpm4b/main.py"
click node_pycore "https://github.com/jdjchelp-jpg/nodebpm4b/blob/master/bpm4b/core.py"
click node_encoder "https://github.com/jdjchelp-jpg/nodebpm4b/blob/master/bpm4b/encoder.py"
click node_pychapters "https://github.com/jdjchelp-jpg/nodebpm4b/blob/master/bpm4b/chapters.py"
click node_metadata "https://github.com/jdjchelp-jpg/nodebpm4b/blob/master/bpm4b/metadata.py"
click node_noise "https://github.com/jdjchelp-jpg/nodebpm4b/blob/master/bpm4b/noise.py"
click node_quality "https://github.com/jdjchelp-jpg/nodebpm4b/blob/master/bpm4b/quality.py"
click node_pipeline "https://github.com/jdjchelp-jpg/nodebpm4b/blob/master/bpm4b/pipeline.py"
click node_config "https://github.com/jdjchelp-jpg/nodebpm4b/blob/master/bpm4b/config.py"
click node_portablecore "https://github.com/jdjchelp-jpg/nodebpm4b/blob/master/BPM4B-Portable/app/lib/core.js"
click node_portablebuilder "https://github.com/jdjchelp-jpg/nodebpm4b/blob/master/BPM4B-Portable/app/lib/audiobook-builder.js"
click node_portableserver "https://github.com/jdjchelp-jpg/nodebpm4b/blob/master/BPM4B-Portable/app/lib/server.js"
click node_portabletts "https://github.com/jdjchelp-jpg/nodebpm4b/blob/master/BPM4B-Portable/app/lib/tts-engine.js"
click node_portableai "https://github.com/jdjchelp-jpg/nodebpm4b/blob/master/BPM4B-Portable/app/lib/ai-engine.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_nodecli,node_web,node_api,node_colab,node_portableserver,node_user toneBlue
class node_core,node_chapterdetect,node_portablecore toneAmber
class node_builder,node_tts,node_pool,node_worker,node_ai,node_abogen,node_portablebuilder,node_portabletts,node_portableai,node_openrouter toneMint
class node_docparser,node_doc2epub,node_epubparser,node_epub2audio,node_voices toneRose
class node_pycli,node_pyapp,node_pycore,node_encoder,node_pychapters,node_metadata,node_noise,node_quality,node_pipeline,node_config toneIndigo
```

## Components

### User interfaces

- [Node CLI](https://github.com/jdjchelp-jpg/nodebpm4b/blob/master/bin/bpm4b.js): `bin/bpm4b.js`
- [Web API](https://github.com/jdjchelp-jpg/nodebpm4b/blob/master/lib/server.js): `lib/server.js`
- [Serverless API](https://github.com/jdjchelp-jpg/nodebpm4b/blob/master/api/index.js): `api/index.js`
- [Colab tunnels](https://github.com/jdjchelp-jpg/nodebpm4b/blob/master/lib/colab-support.js): `lib/colab-support.js`
- [Portable web API](https://github.com/jdjchelp-jpg/nodebpm4b/blob/master/BPM4B-Portable/app/lib/server.js): `BPM4B-Portable/app/lib/server.js`

### Audio conversion

- [Audio operations](https://github.com/jdjchelp-jpg/nodebpm4b/blob/master/lib/core.js): `lib/core.js`
- [Chapter detection](https://github.com/jdjchelp-jpg/nodebpm4b/blob/master/lib/chapter-detector.js): `lib/chapter-detector.js`
- [Portable audio operations](https://github.com/jdjchelp-jpg/nodebpm4b/blob/master/BPM4B-Portable/app/lib/core.js): `BPM4B-Portable/app/lib/core.js`

### Narration

- [Audiobook builder](https://github.com/jdjchelp-jpg/nodebpm4b/blob/master/lib/audiobook-builder.js): `lib/audiobook-builder.js`
- [Speech synthesis](https://github.com/jdjchelp-jpg/nodebpm4b/blob/master/lib/tts-engine.js): `lib/tts-engine.js`
- [TTS worker pool](https://github.com/jdjchelp-jpg/nodebpm4b/blob/master/lib/tts-pool.js): `lib/tts-pool.js`
- [TTS worker](https://github.com/jdjchelp-jpg/nodebpm4b/blob/master/lib/tts-worker.js): `lib/tts-worker.js`
- [AI planning](https://github.com/jdjchelp-jpg/nodebpm4b/blob/master/lib/ai-engine.js): `lib/ai-engine.js`
- [Abogen integration](https://github.com/jdjchelp-jpg/nodebpm4b/blob/master/lib/abogen-integration.js): `lib/abogen-integration.js`
- [Portable audiobook builder](https://github.com/jdjchelp-jpg/nodebpm4b/blob/master/BPM4B-Portable/app/lib/audiobook-builder.js): `BPM4B-Portable/app/lib/audiobook-builder.js`
- [Portable speech synthesis](https://github.com/jdjchelp-jpg/nodebpm4b/blob/master/BPM4B-Portable/app/lib/tts-engine.js): `BPM4B-Portable/app/lib/tts-engine.js`
- [Portable AI planning](https://github.com/jdjchelp-jpg/nodebpm4b/blob/master/BPM4B-Portable/app/lib/ai-engine.js): `BPM4B-Portable/app/lib/ai-engine.js`

### Document conversion

- [Document parser](https://github.com/jdjchelp-jpg/nodebpm4b/blob/master/lib/document-parser.js): `lib/document-parser.js`
- [Document to EPUB](https://github.com/jdjchelp-jpg/nodebpm4b/blob/master/lib/document-to-epub.js): `lib/document-to-epub.js`
- [EPUB parser](https://github.com/jdjchelp-jpg/nodebpm4b/blob/master/lib/epub-parser.js): `lib/epub-parser.js`
- [EPUB audiobook](https://github.com/jdjchelp-jpg/nodebpm4b/blob/master/lib/epub-to-audiobook.js): `lib/epub-to-audiobook.js`
- [Language voices](https://github.com/jdjchelp-jpg/nodebpm4b/blob/master/lib/multi-language-voices.js): `lib/multi-language-voices.js`

### Python processing

- [Python CLI](https://github.com/jdjchelp-jpg/nodebpm4b/blob/master/bpm4b/cli.py): `bpm4b/cli.py`
- [Python application](https://github.com/jdjchelp-jpg/nodebpm4b/blob/master/bpm4b/main.py): `bpm4b/main.py`
- [Python conversion core](https://github.com/jdjchelp-jpg/nodebpm4b/blob/master/bpm4b/core.py): `bpm4b/core.py`
- [Audio encoder](https://github.com/jdjchelp-jpg/nodebpm4b/blob/master/bpm4b/encoder.py): `bpm4b/encoder.py`
- [Chapter generator](https://github.com/jdjchelp-jpg/nodebpm4b/blob/master/bpm4b/chapters.py): `bpm4b/chapters.py`
- [Metadata tools](https://github.com/jdjchelp-jpg/nodebpm4b/blob/master/bpm4b/metadata.py): `bpm4b/metadata.py`
- [Noise reduction](https://github.com/jdjchelp-jpg/nodebpm4b/blob/master/bpm4b/noise.py): `bpm4b/noise.py`
- [Quality assurance](https://github.com/jdjchelp-jpg/nodebpm4b/blob/master/bpm4b/quality.py): `bpm4b/quality.py`
- [Parallel pipeline](https://github.com/jdjchelp-jpg/nodebpm4b/blob/master/bpm4b/pipeline.py): `bpm4b/pipeline.py`
- [Configuration](https://github.com/jdjchelp-jpg/nodebpm4b/blob/master/bpm4b/config.py): `bpm4b/config.py`

### Other components

- **User**
- **OpenRouter**

## Connections

- User → Node CLI: runs command (evidence: `README.md`)
- User → Web API: uses interface (evidence: `README.md`)
- Node CLI → Audio operations: invokes conversion (evidence: `bin/bpm4b.js`)
- Node CLI → Web API: starts web (evidence: `bin/bpm4b.js`)
- Web API → Audio operations: routes audio jobs (evidence: `lib/server.js`)
- Web API → Audiobook builder: routes audiobook jobs (evidence: `lib/server.js`)
- Web API → Document to EPUB: routes document conversion (evidence: `lib/server.js`)
- Web API → EPUB audiobook: routes EPUB conversion (evidence: `lib/server.js`)
- Web API → AI planning: uses narration analysis (evidence: `lib/server.js`)
- Web API → Colab tunnels: configures tunnels (evidence: `lib/server.js`)
- Serverless API → Audio operations: uses audio operations (evidence: `api/index.js`)
- Audiobook builder → Document parser: parses documents (evidence: `lib/audiobook-builder.js`)
- Audiobook builder → Chapter detection: detects chapters (evidence: `lib/audiobook-builder.js`)
- Audiobook builder → Speech synthesis: generates speech (evidence: `lib/audiobook-builder.js`)
- Speech synthesis → TTS worker pool: submits synthesis (evidence: `lib/tts-engine.js`)
- TTS worker pool → TTS worker: dispatches chunks
- AI planning → OpenRouter: requests analysis (evidence: `lib/ai-engine.js`)
- EPUB audiobook → EPUB parser: parses EPUB (evidence: `lib/epub-to-audiobook.js`)
- EPUB audiobook → Language voices: selects voices (evidence: `lib/epub-to-audiobook.js`)
- EPUB audiobook → Speech synthesis: synthesizes chapters (evidence: `lib/epub-to-audiobook.js`)
- EPUB audiobook → Abogen integration: supports engine (evidence: `lib/epub-to-audiobook.js`)
- Document to EPUB → EPUB parser: uses EPUB parsing (evidence: `lib/document-to-epub.js`)
- User → Python CLI: runs command (evidence: `README.md`)
- Python CLI → Python application: starts processing
- Python application → Audio encoder: encodes audio (evidence: `bpm4b/main.py`)
- Python application → Noise reduction: reduces noise (evidence: `bpm4b/main.py`)
- Python application → Chapter generator: generates chapters (evidence: `bpm4b/main.py`)
- Python application → Metadata tools: aggregates metadata (evidence: `bpm4b/main.py`)
- Python application → Parallel pipeline: runs pipeline (evidence: `bpm4b/main.py`)
- Python application → Quality assurance: checks quality (evidence: `bpm4b/main.py`)
- Python conversion core → Audio encoder: uses encoder (evidence: `bpm4b/core.py`)
- Python conversion core → Chapter generator: uses chapters (evidence: `bpm4b/core.py`)
- Python conversion core → Noise reduction: uses noise tools (evidence: `bpm4b/core.py`)
- Python conversion core → Metadata tools: uses metadata (evidence: `bpm4b/core.py`)
- Python conversion core → Quality assurance: uses quality checks (evidence: `bpm4b/core.py`)
- Parallel pipeline → Audio encoder: runs encoding (evidence: `bpm4b/pipeline.py`)
- Portable audio operations → User: produces conversions
- Portable web API → Portable audio operations: routes audio jobs (evidence: `BPM4B-Portable/app/lib/server.js`)
- Portable web API → Portable audiobook builder: routes audiobook jobs (evidence: `BPM4B-Portable/app/lib/server.js`)
- Portable audiobook builder → Portable speech synthesis: uses synthesis (evidence: `BPM4B-Portable/app/lib/audiobook-builder.js`)
- Portable web API → Portable AI planning: uses AI features (evidence: `BPM4B-Portable/app/lib/server.js`)
