# cypher-monarch/chrona architecture

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

- Interactive diagram: https://gitdiagram.com/cypher-monarch/chrona
- Repository: https://github.com/cypher-monarch/chrona

## Overview

Chrona is an offline desktop document-to-speech and MP3 application. The main workflow is to choose a TXT, DOCX, or PDF file, extract its text, then speak it, save an MP3, or do both. Voice selection and speed controls are present in the UI; the sampled synthesis code does not show speed or volume being passed to Piper. The README also documents volume controls, which are not evident in the sampled UI source. The graph includes voice discovery, audio playback/export, and the update check; unsampled capability wiring is omitted.

Main entry points: [`src/ui/main_window.py`](https://github.com/cypher-monarch/chrona/blob/master/src/ui/main_window.py) (Conversion UI and controls), [`src/audio/exporters.py`](https://github.com/cypher-monarch/chrona/blob/master/src/audio/exporters.py) (MP3 export), [`src/updates.py`](https://github.com/cypher-monarch/chrona/blob/master/src/updates.py) (Update checker), [`src/audio/engine.py`](https://github.com/cypher-monarch/chrona/blob/master/src/audio/engine.py) (Speech synthesis)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Desktop interface"]
  node_entry["Application entry<br/>[chrona.py]"]
  node_window["Conversion UI and controls<br/>[main_window.py]"]
end

subgraph group_audio["Document and audio"]
  node_reader["Document reader<br/>[reader.py]"]
  node_piper["Piper discovery<br/>[piper.py]"]
  node_engine["Speech synthesis<br/>[engine.py]"]
  node_exporter["MP3 export<br/>[exporters.py]"]
  node_audio_conversion["WAV to MP3 conversion<br/>[exporters.py]"]
end

subgraph group_integrations["System integrations"]
  node_updates["Update checker<br/>[updates.py]"]
  node_constants["App configuration<br/>[constants.py]"]
end

node_user(("User"))
node_document["Selected document"]
node_voicefiles["Installed voice models"]
node_output["Chrona MP3 folder"]
node_piperbin["Piper executable"]
node_player["Qt audio playback"]
node_update_service["Version endpoint"]

node_user -->|"launches"| node_entry
node_entry -->|"creates"| node_window
node_user -->|"chooses file"| node_window
node_document -->|"selected input"| node_window
node_window -->|"reads document"| node_reader
node_window -->|"discovers voices"| node_piper
node_piper -->|"scans models"| node_voicefiles
node_window -->|"renders speech"| node_engine
node_engine -->|"invokes"| node_piperbin
node_window -->|"plays WAV"| node_player
node_window -->|"requests MP3"| node_exporter
node_exporter -->|"renders WAV"| node_engine
node_exporter -->|"converts WAV"| node_audio_conversion
node_exporter -->|"writes MP3"| node_output
node_window -->|"checks versions"| node_updates
node_updates -->|"requests version"| node_update_service
node_updates -->|"reads settings"| node_constants
node_exporter -->|"reads folder"| node_constants

click node_entry "https://github.com/cypher-monarch/chrona/blob/master/src/chrona.py"
click node_window "https://github.com/cypher-monarch/chrona/blob/master/src/ui/main_window.py"
click node_reader "https://github.com/cypher-monarch/chrona/blob/master/src/documents/reader.py"
click node_piper "https://github.com/cypher-monarch/chrona/blob/master/src/audio/piper.py"
click node_engine "https://github.com/cypher-monarch/chrona/blob/master/src/audio/engine.py"
click node_exporter "https://github.com/cypher-monarch/chrona/blob/master/src/audio/exporters.py"
click node_updates "https://github.com/cypher-monarch/chrona/blob/master/src/updates.py"
click node_constants "https://github.com/cypher-monarch/chrona/blob/master/src/constants.py"
click node_audio_conversion "https://github.com/cypher-monarch/chrona/blob/master/src/audio/exporters.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_entry,node_window,node_user toneBlue
class node_reader,node_piper,node_engine,node_exporter,node_audio_conversion toneAmber
class node_updates,node_constants toneMint
class node_document,node_voicefiles,node_output,node_piperbin,node_player,node_update_service toneIndigo
```

## Components

### Desktop interface

- [Application entry](https://github.com/cypher-monarch/chrona/blob/master/src/chrona.py): `src/chrona.py`
- [Conversion UI and controls](https://github.com/cypher-monarch/chrona/blob/master/src/ui/main_window.py): `src/ui/main_window.py`

### Document and audio

- [Document reader](https://github.com/cypher-monarch/chrona/blob/master/src/documents/reader.py): `src/documents/reader.py`
- [Piper discovery](https://github.com/cypher-monarch/chrona/blob/master/src/audio/piper.py): `src/audio/piper.py`
- [Speech synthesis](https://github.com/cypher-monarch/chrona/blob/master/src/audio/engine.py): `src/audio/engine.py`
- [MP3 export](https://github.com/cypher-monarch/chrona/blob/master/src/audio/exporters.py): `src/audio/exporters.py`
- [WAV to MP3 conversion](https://github.com/cypher-monarch/chrona/blob/master/src/audio/exporters.py): `src/audio/exporters.py`

### System integrations

- [Update checker](https://github.com/cypher-monarch/chrona/blob/master/src/updates.py): `src/updates.py`
- [App configuration](https://github.com/cypher-monarch/chrona/blob/master/src/constants.py): `src/constants.py`

### Other components

- **User**
- **Selected document**
- **Installed voice models**
- **Chrona MP3 folder**
- **Piper executable**
- **Qt audio playback**
- **Version endpoint**

## Connections

- User → Application entry: launches
- Application entry → Conversion UI and controls: creates
- User → Conversion UI and controls: chooses file
- Selected document → Conversion UI and controls: selected input
- Conversion UI and controls → Document reader: reads document
- Conversion UI and controls → Piper discovery: discovers voices
- Piper discovery → Installed voice models: scans models
- Conversion UI and controls → Speech synthesis: renders speech
- Speech synthesis → Piper executable: invokes
- Conversion UI and controls → Qt audio playback: plays WAV
- Conversion UI and controls → MP3 export: requests MP3
- MP3 export → Speech synthesis: renders WAV
- MP3 export → WAV to MP3 conversion: converts WAV
- MP3 export → Chrona MP3 folder: writes MP3
- Conversion UI and controls → Update checker: checks versions
- Update checker → Version endpoint: requests version
- Update checker → App configuration: reads settings
- MP3 export → App configuration: reads folder