# nynchezyabka/rozittaparser architecture

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

- Interactive diagram: https://gitdiagram.com/nynchezyabka/rozittaparser
- Repository: https://github.com/nynchezyabka/rozittaparser

## Overview

#### 1. Product and entry points
Rozitta Parser is a local Python desktop application for authenticating to Telegram, downloading chat history/media into portable local archives, and exporting readable or RAG-ready documents. Runtime starts at `main.py`, which composes the application shell in `ui/main_window.py`; global settings and output locations are centralized in `config.py`.

#### 2. Desktop UI and feature orchestration
The main window coordinates feature-specific screens rather than exposing a web/API service. Each major user journey has a UI module paired with an API/service-facing module:
- Authentication: `features/auth/ui.py`, `features/auth/api.py`
- Chat selection: `features/chats/ui.py`, `features/chats/api.py`
- Archive parsing: `features/parser/ui.py`, `features/parser/api.py`
Shared desktop widgets, styles, and calendar controls reside in `core/ui_shared/widgets.py`, `core/ui_shared/styles.py`, and `core/ui_shared/calendar.py`.

#### 3. Telegram access and archive acquisition
Telegram is the principal external service, accessed through the auth/chat/parser feature APIs. The flow is: establish a Telegram session (classic API credentials or Telegram Desktop `tdata` import), enumerate eligible dialogs, let the user select chats/options, then fetch messages, discussion threads, participants, and media into a local archive. Networking accommodates proxy usage through `socks.py` and `sockshandler.py`; retry/rate-limit behavior is isolated in `core/retry.py`. README identifies Telethon as the Telegram client runtime behavior source.

#### 4. Local persistence and archive lifecycle
Downloaded content is persisted locally in SQLite plus an output directory containing media and generated documents. `core/database.py` is the storage boundary for archive records; `check_db.py` supports database inspection/maintenance. Archive updates and longer-running update work are separated into `features/update_archive/worker.py` and `features/update_archive/report_dialog.py`. The design keeps Telegram acquisition distinct from subsequent offline export and inspection.

#### 5. Parsing, media, and speech-to-text pipeline
Parser orchestration turns Telegram entities into normalized local records and downloaded assets via `features/parser/api.py`. Audio/video-note transcription is an optional local post-processing stage: `core/stt/worker.py` coordinates background work, `core/stt/audio_converter.py` prepares supported audio, and `core/stt/whisper_manager.py` manages local Whisper inference. This boundary avoids a cloud transcription dependency; transcription text can then be included in exports.

#### 6. Export and knowledge-corpus generation
The export subsystem reads local archive data and renders DOCX, Markdown, HTML, or JSON, with filtering and grouping options such as dates, posts, participants, and reply context. `features/export/generator.py` is the central rendering coordinator, while `features/export/filters.py` and `features/export/participants.py` shape the selected message set. `features/export/knowledge_base.py` implements AI-oriented corpus/chunk preparation; `features/export/xml_magic.py` is the specialized document/XML formatting boundary.

#### 7. Operational boundaries
The application is intended to run locally on Python 3.10–3.13, with portable binary builds produced by `.github/workflows/build_binaries.yml`. It depends materially on Telegram, local SQLite storage, local filesystem media/output directories, optional SOCKS/MTProto proxy connectivity, and local Whisper models/runtime. Cross-cutting error, logging, merge, and utility behavior is concentrated in `core/exceptions.py`, `core/logger.py`, and `core/merger.py`.

Main entry points: [`ui/main_window.py`](https://github.com/nynchezyabka/rozittaparser/blob/main/ui/main_window.py) (Main window), [`features/parser/api.py`](https://github.com/nynchezyabka/rozittaparser/blob/main/features/parser/api.py) (Archive acquisition), [`core/database.py`](https://github.com/nynchezyabka/rozittaparser/blob/main/core/database.py) (Archive database), [`core/stt/worker.py`](https://github.com/nynchezyabka/rozittaparser/blob/main/core/stt/worker.py) (Local transcription)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop application"]
  node_entry["Application entry<br/>Python runtime<br/>[main.py]"]
  node_window["Main window<br/>Desktop shell<br/>[main_window.py]"]
  node_config["Settings and output paths<br/>Configuration<br/>[config.py]"]
  node_shared_ui["Shared UI controls<br/>UI toolkit<br/>[widgets.py]"]
end

subgraph group_telegram["Telegram acquisition"]
  node_auth_ui["Authentication screen<br/>Feature UI<br/>[ui.py]"]
  node_auth_api["Authentication service<br/>Telegram feature API<br/>[api.py]"]
  node_chats_ui["Chat selection screen<br/>Feature UI<br/>[ui.py]"]
  node_chats_api["Dialog service<br/>Telegram feature API<br/>[api.py]"]
  node_parser_ui["Archive parser screen<br/>Feature UI<br/>[ui.py]"]
  node_parser_api["Archive acquisition<br/>Parser orchestration<br/>[api.py]"]
  node_telegram{{"Telegram<br/>External service"}}
  node_network["Proxy and retry<br/>Network resilience<br/>[socks.py]"]
end

subgraph group_local["Local archive and processing"]
  node_database[("Archive database<br/>SQLite storage<br/>[database.py]")]
  node_filesystem["Archive files<br/>Local filesystem"]
  node_archive_update["Archive updates<br/>Background worker<br/>[worker.py]"]
  node_stt["Local transcription<br/>Speech-to-text worker<br/>[worker.py]"]
  node_whisper{{"Whisper inference<br/>Local model runtime<br/>[whisper_manager.py]"}}
end

subgraph group_export["Export and corpus"]
  node_export_generator["Export generator<br/>Rendering coordinator<br/>[generator.py]"]
  node_knowledge_base["Knowledge corpus builder<br/>Corpus preparation<br/>[knowledge_base.py]"]
end

node_entry -->|"launches"| node_window
node_entry -->|"loads"| node_config
node_window -->|"uses"| node_shared_ui
node_window -->|"hosts"| node_auth_ui
node_window -->|"hosts"| node_chats_ui
node_window -->|"hosts"| node_parser_ui
node_auth_ui -->|"authenticates through"| node_auth_api
node_chats_ui -->|"selects through"| node_chats_api
node_parser_ui -->|"starts acquisition"| node_parser_api
node_auth_api -->|"establishes session"| node_telegram
node_chats_api -->|"lists dialogs"| node_telegram
node_parser_api -->|"downloads content"| node_telegram
node_auth_api -.->|"uses"| node_network
node_parser_api -.->|"uses"| node_network
node_parser_api -->|"normalizes records into"| node_database
node_parser_api -->|"writes media to"| node_filesystem
node_archive_update -->|"updates"| node_database
node_stt -->|"reads audio from"| node_filesystem
node_stt -->|"runs inference with"| node_whisper
node_stt -->|"stores transcripts"| node_database
node_export_generator -->|"reads archive data"| node_database
node_export_generator -->|"writes documents to"| node_filesystem
node_knowledge_base -->|"reads selected content"| node_database
node_knowledge_base -->|"writes corpus files"| node_filesystem

click node_entry "https://github.com/nynchezyabka/rozittaparser/blob/main/main.py"
click node_window "https://github.com/nynchezyabka/rozittaparser/blob/main/ui/main_window.py"
click node_config "https://github.com/nynchezyabka/rozittaparser/blob/main/config.py"
click node_shared_ui "https://github.com/nynchezyabka/rozittaparser/blob/main/core/ui_shared/widgets.py"
click node_auth_ui "https://github.com/nynchezyabka/rozittaparser/blob/main/features/auth/ui.py"
click node_auth_api "https://github.com/nynchezyabka/rozittaparser/blob/main/features/auth/api.py"
click node_chats_ui "https://github.com/nynchezyabka/rozittaparser/blob/main/features/chats/ui.py"
click node_chats_api "https://github.com/nynchezyabka/rozittaparser/blob/main/features/chats/api.py"
click node_parser_ui "https://github.com/nynchezyabka/rozittaparser/blob/main/features/parser/ui.py"
click node_parser_api "https://github.com/nynchezyabka/rozittaparser/blob/main/features/parser/api.py"
click node_network "https://github.com/nynchezyabka/rozittaparser/blob/main/socks.py"
click node_database "https://github.com/nynchezyabka/rozittaparser/blob/main/core/database.py"
click node_archive_update "https://github.com/nynchezyabka/rozittaparser/blob/main/features/update_archive/worker.py"
click node_stt "https://github.com/nynchezyabka/rozittaparser/blob/main/core/stt/worker.py"
click node_whisper "https://github.com/nynchezyabka/rozittaparser/blob/main/core/stt/whisper_manager.py"
click node_export_generator "https://github.com/nynchezyabka/rozittaparser/blob/main/features/export/generator.py"
click node_knowledge_base "https://github.com/nynchezyabka/rozittaparser/blob/main/features/export/knowledge_base.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_config,node_shared_ui toneBlue
class node_auth_ui,node_auth_api,node_chats_ui,node_chats_api,node_parser_ui,node_parser_api,node_telegram,node_network toneAmber
class node_database,node_filesystem,node_archive_update,node_stt,node_whisper toneMint
class node_export_generator,node_knowledge_base toneRose
```

## Components

### Desktop application

- [Application entry](https://github.com/nynchezyabka/rozittaparser/blob/main/main.py): Python runtime · Starts and composes the local desktop application. · `main.py`
- [Main window](https://github.com/nynchezyabka/rozittaparser/blob/main/ui/main_window.py): Desktop shell · Coordinates feature screens and user journeys. · `ui/main_window.py`
- [Settings and output paths](https://github.com/nynchezyabka/rozittaparser/blob/main/config.py): Configuration · `config.py`
- [Shared UI controls](https://github.com/nynchezyabka/rozittaparser/blob/main/core/ui_shared/widgets.py): UI toolkit · `core/ui_shared/widgets.py`

### Telegram acquisition

- [Authentication screen](https://github.com/nynchezyabka/rozittaparser/blob/main/features/auth/ui.py): Feature UI · `features/auth/ui.py`
- [Authentication service](https://github.com/nynchezyabka/rozittaparser/blob/main/features/auth/api.py): Telegram feature API · Creates sessions from credentials or Telegram Desktop tdata. · `features/auth/api.py`
- [Chat selection screen](https://github.com/nynchezyabka/rozittaparser/blob/main/features/chats/ui.py): Feature UI · `features/chats/ui.py`
- [Dialog service](https://github.com/nynchezyabka/rozittaparser/blob/main/features/chats/api.py): Telegram feature API · Enumerates eligible dialogs and selection options. · `features/chats/api.py`
- [Archive parser screen](https://github.com/nynchezyabka/rozittaparser/blob/main/features/parser/ui.py): Feature UI · `features/parser/ui.py`
- [Archive acquisition](https://github.com/nynchezyabka/rozittaparser/blob/main/features/parser/api.py): Parser orchestration · Fetches messages, threads, participants, and media into local records. · `features/parser/api.py`
- **Telegram**: External service
- [Proxy and retry](https://github.com/nynchezyabka/rozittaparser/blob/main/socks.py): Network resilience · Provides SOCKS/MTProto connectivity and rate-limit retry behavior. · `socks.py`

### Local archive and processing

- [Archive database](https://github.com/nynchezyabka/rozittaparser/blob/main/core/database.py): SQLite storage · Storage boundary for downloaded archive records. · `core/database.py`
- **Archive files**: Local filesystem · Stores media and generated output documents.
- [Archive updates](https://github.com/nynchezyabka/rozittaparser/blob/main/features/update_archive/worker.py): Background worker · Runs longer-lived local archive update work. · `features/update_archive/worker.py`
- [Local transcription](https://github.com/nynchezyabka/rozittaparser/blob/main/core/stt/worker.py): Speech-to-text worker · Coordinates optional audio and video-note transcription. · `core/stt/worker.py`
- [Whisper inference](https://github.com/nynchezyabka/rozittaparser/blob/main/core/stt/whisper_manager.py): Local model runtime · Manages local Whisper model inference. · `core/stt/whisper_manager.py`

### Export and corpus

- [Export generator](https://github.com/nynchezyabka/rozittaparser/blob/main/features/export/generator.py): Rendering coordinator · Builds DOCX, Markdown, HTML, and JSON from local archives. · `features/export/generator.py`
- [Knowledge corpus builder](https://github.com/nynchezyabka/rozittaparser/blob/main/features/export/knowledge_base.py): Corpus preparation · Prepares AI-oriented corpus chunks from selected content. · `features/export/knowledge_base.py`

## Connections

- Application entry → Main window: launches
- Application entry → Settings and output paths: loads
- Main window → Shared UI controls: uses
- Main window → Authentication screen: hosts
- Main window → Chat selection screen: hosts
- Main window → Archive parser screen: hosts
- Authentication screen → Authentication service: authenticates through
- Chat selection screen → Dialog service: selects through
- Archive parser screen → Archive acquisition: starts acquisition
- Authentication service → Telegram: establishes session
- Dialog service → Telegram: lists dialogs
- Archive acquisition → Telegram: downloads content
- Authentication service → Proxy and retry: uses
- Archive acquisition → Proxy and retry: uses
- Archive acquisition → Archive database: normalizes records into
- Archive acquisition → Archive files: writes media to
- Archive updates → Archive database: updates
- Local transcription → Archive files: reads audio from
- Local transcription → Whisper inference: runs inference with
- Local transcription → Archive database: stores transcripts
- Export generator → Archive database: reads archive data
- Export generator → Archive files: writes documents to
- Knowledge corpus builder → Archive database: reads selected content
- Knowledge corpus builder → Archive files: writes corpus files