# ssnangua/colortxt architecture

> Architecture diagram of the GitHub repository ssnangua/colortxt, 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/ssnangua/colortxt
- Repository: https://github.com/ssnangua/colortxt

## Overview

ColorTxt is a desktop novel-reading app for local text and converted ebook files, with book-source discovery and AI-assisted reading. The main workflow is to open a file, convert supported ebook formats to Markdown, prepare display text and chapter mappings, then read and annotate it. Separate branches provide online book search, dictionary lookup, voice reading, and AI tools. Paths and the display-pipeline link are supported by the tree and sampled source; other feature connections reflect README capabilities, not inspected call sites.

Main entry points: [`src/renderer/src/services/fileOpenService.ts`](https://github.com/ssnangua/colortxt/blob/main/src/renderer/src/services/fileOpenService.ts) (Open files), [`src/renderer/src/App.vue`](https://github.com/ssnangua/colortxt/blob/main/src/renderer/src/App.vue) (Reader), [`src/renderer/src/ebook/convert/convertEbookToMarkdown.ts`](https://github.com/ssnangua/colortxt/blob/main/src/renderer/src/ebook/convert/convertEbookToMarkdown.ts) (Ebook conversion), [`src/renderer/src/composables/useTxtStreamPipeline.ts`](https://github.com/ssnangua/colortxt/blob/main/src/renderer/src/composables/useTxtStreamPipeline.ts) (Display preparation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop shell"]
  node_reader["Reader<br/>[App.vue]"]
  node_open["Open files<br/>[fileOpenService.ts]"]
end

subgraph group_reading["Reading experience"]
  node_convert["Ebook conversion"]
  node_formats["Format parsers<br/>[parseEpub.ts]"]
  node_stream["Display preparation"]
  node_display["Reader formatting"]
  node_readerui["Reading view<br/>[ReaderMain.vue]"]
  node_annotations["Annotations"]
end

subgraph group_discovery["Book discovery"]
  node_booksources["Book-source UI<br/>[FindBookPanel.vue]"]
  node_search["Multi-source search<br/>[searchService.ts]"]
  node_sourceengine["Source rule engine<br/>[webBook.ts]"]
end

subgraph group_ai["AI features"]
  node_assistant["AI assistant"]
  node_aiipc["AI services<br/>[registerAiIpc.ts]"]
  node_portrait["Character portraits"]
  node_vector["Book vector index"]
end

subgraph group_services["Reading services"]
  node_dictionary["Dictionary lookup"]
  node_voice["Voice reading"]
  node_tts["Speech providers"]
  node_webdav["WebDAV sync"]
end

node_user(("Reader user"))

node_user -->|"uses"| node_reader
node_reader -->|"opens files"| node_open
node_open -->|"converts ebooks"| node_convert
node_convert -->|"parses formats"| node_formats
node_open -->|"loads text"| node_stream
node_stream -->|"formats lines"| node_display
node_display -->|"provides display text"| node_readerui
node_readerui -->|"supports marking"| node_annotations
node_user -->|"searches books"| node_booksources
node_booksources -->|"starts search"| node_search
node_search -->|"queries sources"| node_sourceengine
node_user -->|"asks questions"| node_assistant
node_assistant -->|"requests AI"| node_aiipc
node_portrait -->|"builds index"| node_vector
node_user -->|"looks up words"| node_dictionary
node_user -->|"starts narration"| node_voice
node_voice -->|"routes synthesis"| node_tts
node_user -->|"syncs settings"| node_webdav

click node_reader "https://github.com/ssnangua/colortxt/blob/main/src/renderer/src/App.vue"
click node_open "https://github.com/ssnangua/colortxt/blob/main/src/renderer/src/services/fileOpenService.ts"
click node_convert "https://github.com/ssnangua/colortxt/blob/main/src/renderer/src/ebook/convert/convertEbookToMarkdown.ts"
click node_formats "https://github.com/ssnangua/colortxt/blob/main/src/renderer/src/ebook/convert/parseEpub.ts"
click node_stream "https://github.com/ssnangua/colortxt/blob/main/src/renderer/src/composables/useTxtStreamPipeline.ts"
click node_display "https://github.com/ssnangua/colortxt/blob/main/src/renderer/src/reader/readerDisplayPipeline.ts"
click node_readerui "https://github.com/ssnangua/colortxt/blob/main/src/renderer/src/components/ReaderMain.vue"
click node_annotations "https://github.com/ssnangua/colortxt/blob/main/src/renderer/src/composables/useReaderAnnotations.ts"
click node_booksources "https://github.com/ssnangua/colortxt/blob/main/src/renderer/src/bookSource/components/FindBookPanel.vue"
click node_search "https://github.com/ssnangua/colortxt/blob/main/src/main/bookSource/searchService.ts"
click node_sourceengine "https://github.com/ssnangua/colortxt/blob/main/src/main/bookSource/engine/webBook.ts"
click node_assistant "https://github.com/ssnangua/colortxt/blob/main/src/renderer/src/components/AiAssistantPanel.vue"
click node_aiipc "https://github.com/ssnangua/colortxt/blob/main/src/main/registerAiIpc.ts"
click node_portrait "https://github.com/ssnangua/colortxt/blob/main/src/renderer/src/composables/useCharacterPortraitRetrieve.ts"
click node_vector "https://github.com/ssnangua/colortxt/blob/main/src/renderer/src/ai/buildBookVectorIndex.ts"
click node_dictionary "https://github.com/ssnangua/colortxt/blob/main/src/main/dictionary/dictionaryService.ts"
click node_voice "https://github.com/ssnangua/colortxt/blob/main/src/renderer/src/services/voiceRead/voiceReadEngineRouting.ts"
click node_tts "https://github.com/ssnangua/colortxt/blob/main/src/main/voiceRead/providerRegistry.ts"
click node_webdav "https://github.com/ssnangua/colortxt/blob/main/src/main/webdav/registerWebDavIpc.ts"

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_reader,node_open,node_user toneBlue
class node_convert,node_formats,node_stream,node_display,node_readerui,node_annotations toneAmber
class node_booksources,node_search,node_sourceengine toneMint
class node_assistant,node_aiipc,node_portrait,node_vector toneRose
class node_dictionary,node_voice,node_tts,node_webdav toneIndigo
```

## Components

### Desktop shell

- [Reader](https://github.com/ssnangua/colortxt/blob/main/src/renderer/src/App.vue): `src/renderer/src/App.vue`
- [Open files](https://github.com/ssnangua/colortxt/blob/main/src/renderer/src/services/fileOpenService.ts): `src/renderer/src/services/fileOpenService.ts`

### Reading experience

- [Ebook conversion](https://github.com/ssnangua/colortxt/blob/main/src/renderer/src/ebook/convert/convertEbookToMarkdown.ts): `src/renderer/src/ebook/convert/convertEbookToMarkdown.ts`
- [Format parsers](https://github.com/ssnangua/colortxt/blob/main/src/renderer/src/ebook/convert/parseEpub.ts): `src/renderer/src/ebook/convert/parseEpub.ts`
- [Display preparation](https://github.com/ssnangua/colortxt/blob/main/src/renderer/src/composables/useTxtStreamPipeline.ts): `src/renderer/src/composables/useTxtStreamPipeline.ts`
- [Reader formatting](https://github.com/ssnangua/colortxt/blob/main/src/renderer/src/reader/readerDisplayPipeline.ts): `src/renderer/src/reader/readerDisplayPipeline.ts`
- [Reading view](https://github.com/ssnangua/colortxt/blob/main/src/renderer/src/components/ReaderMain.vue): `src/renderer/src/components/ReaderMain.vue`
- [Annotations](https://github.com/ssnangua/colortxt/blob/main/src/renderer/src/composables/useReaderAnnotations.ts): `src/renderer/src/composables/useReaderAnnotations.ts`

### Book discovery

- [Book-source UI](https://github.com/ssnangua/colortxt/blob/main/src/renderer/src/bookSource/components/FindBookPanel.vue): `src/renderer/src/bookSource/components/FindBookPanel.vue`
- [Multi-source search](https://github.com/ssnangua/colortxt/blob/main/src/main/bookSource/searchService.ts): `src/main/bookSource/searchService.ts`
- [Source rule engine](https://github.com/ssnangua/colortxt/blob/main/src/main/bookSource/engine/webBook.ts): `src/main/bookSource/engine/webBook.ts`

### AI features

- [AI assistant](https://github.com/ssnangua/colortxt/blob/main/src/renderer/src/components/AiAssistantPanel.vue): `src/renderer/src/components/AiAssistantPanel.vue`
- [AI services](https://github.com/ssnangua/colortxt/blob/main/src/main/registerAiIpc.ts): `src/main/registerAiIpc.ts`
- [Character portraits](https://github.com/ssnangua/colortxt/blob/main/src/renderer/src/composables/useCharacterPortraitRetrieve.ts): `src/renderer/src/composables/useCharacterPortraitRetrieve.ts`
- [Book vector index](https://github.com/ssnangua/colortxt/blob/main/src/renderer/src/ai/buildBookVectorIndex.ts): `src/renderer/src/ai/buildBookVectorIndex.ts`

### Reading services

- [Dictionary lookup](https://github.com/ssnangua/colortxt/blob/main/src/main/dictionary/dictionaryService.ts): `src/main/dictionary/dictionaryService.ts`
- [Voice reading](https://github.com/ssnangua/colortxt/blob/main/src/renderer/src/services/voiceRead/voiceReadEngineRouting.ts): `src/renderer/src/services/voiceRead/voiceReadEngineRouting.ts`
- [Speech providers](https://github.com/ssnangua/colortxt/blob/main/src/main/voiceRead/providerRegistry.ts): `src/main/voiceRead/providerRegistry.ts`
- [WebDAV sync](https://github.com/ssnangua/colortxt/blob/main/src/main/webdav/registerWebDavIpc.ts): `src/main/webdav/registerWebDavIpc.ts`

### Other components

- **Reader user**

## Connections

- Reader user → Reader: uses
- Reader → Open files: opens files
- Open files → Ebook conversion: converts ebooks
- Ebook conversion → Format parsers: parses formats
- Open files → Display preparation: loads text
- Display preparation → Reader formatting: formats lines
- Reader formatting → Reading view: provides display text
- Reading view → Annotations: supports marking
- Reader user → Book-source UI: searches books
- Book-source UI → Multi-source search: starts search
- Multi-source search → Source rule engine: queries sources
- Reader user → AI assistant: asks questions
- AI assistant → AI services: requests AI
- Character portraits → Book vector index: builds index
- Reader user → Dictionary lookup: looks up words
- Reader user → Voice reading: starts narration
- Voice reading → Speech providers: routes synthesis
- Reader user → WebDAV sync: syncs settings