# shoralbrt/transliterator architecture

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

- Interactive diagram: https://gitdiagram.com/shoralbrt/transliterator
- Repository: https://github.com/shoralbrt/transliterator

## Overview

Transliterator converts vocalised Arabic into Cyrillic or academic Latin through a segment-based tajweed pipeline; the same core serves the browser and CLI. The browser also supports corpus surahs, reading settings, editable profiles, localization, and feedback. The excerpts show the core processing stages and some service wiring; other browser and CLI capabilities are included where the README documents them, so their internal connections are not inferred beyond that evidence.

Main entry points: [`Transliterator.Core/Services/Rules/RulesService.cs`](https://github.com/shoralbrt/transliterator/blob/master/Transliterator.Core/Services/Rules/RulesService.cs) (Tajweed orchestration), [`Transliterator.Core/Services/TransliterationService.cs`](https://github.com/shoralbrt/transliterator/blob/master/Transliterator.Core/Services/TransliterationService.cs) (Transliteration service), [`Transliterator.Web/Program.cs`](https://github.com/shoralbrt/transliterator/blob/master/Transliterator.Web/Program.cs) (Web application), [`Transliterator.Core/Repositories/UserProfileRepository.cs`](https://github.com/shoralbrt/transliterator/blob/master/Transliterator.Core/Repositories/UserProfileRepository.cs) (User profile repository)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["User interfaces"]
  node_web["Web application<br/>[Program.cs]"]
  node_webpage["Browser page<br/>[page.js]"]
  node_cli["CLI application<br/>[CliApp.cs]"]
end

subgraph group_pipeline["Transliteration pipeline"]
  node_normalizer["Orthography normalization"]
  node_parser["Arabic segment parser<br/>[ArabicParser.cs]"]
  node_segments["Phonological segments<br/>[Segment.cs]"]
  node_rules["Tajweed orchestration<br/>[RulesService.cs]"]
  node_waqf["Pause and wasl<br/>[WaqfRule.cs]"]
  node_article["Article assimilation<br/>[ArticleRule.cs]"]
  node_assimilation["Consonant assimilation"]
  node_nasal["Nasal rules<br/>[NasalRule.cs]"]
  node_emphasis["Emphasis rules<br/>[EmphasisRule.cs]"]
  node_madd["Madd rules<br/>[MaddRule.cs]"]
  node_qalqalah["Qalqalah rules<br/>[QalqalahRule.cs]"]
  node_renderer["Profile renderer"]
  node_service["Transliteration service"]
  node_reading["Reading options<br/>[ReadingOptions.cs]"]
end

subgraph group_profiles["Profiles and corpus"]
  node_profilesvc["User profile repository"]
  node_builtins["Built-in profiles"]
  node_corpus[("Surah corpus")]
  node_store[("Browser local storage")]
  node_profileeditor["Profile editor<br/>[ProfileEditor.cs]"]
end

subgraph group_support["Browser features"]
  node_panels["Settings panels<br/>[PagePanels.cs]"]
  node_feedback["Feedback client<br/>[FeedbackClient.cs]"]
  node_worker["Feedback worker<br/>[feedback.js]"]
end

node_user(("User"))
node_github["GitHub issues"]

node_user -->|"enters text"| node_webpage
node_web -->|"registers service"| node_service
node_webpage -->|"requests transliteration"| node_service
node_user -->|"provides input"| node_cli
node_cli -->|"requests transliteration"| node_service
node_service -->|"loads profile"| node_profilesvc
node_service -->|"normalizes text"| node_normalizer
node_service -->|"parses text"| node_parser
node_parser -->|"creates segments"| node_segments
node_service -->|"applies rules"| node_rules
node_rules -->|"applies first"| node_waqf
node_rules -->|"applies"| node_article
node_rules -->|"applies"| node_assimilation
node_rules -->|"applies"| node_nasal
node_rules -->|"applies"| node_emphasis
node_rules -->|"applies"| node_madd
node_rules -->|"applies"| node_qalqalah
node_service -->|"renders segments"| node_renderer
node_renderer -->|"uses profile"| node_profilesvc
node_user -->|"chooses surah"| node_corpus
node_web -->|"registers repository"| node_corpus
node_web -->|"registers repository"| node_profilesvc
node_profilesvc -->|"loads built-ins"| node_builtins
node_profilesvc -->|"reads and writes"| node_store
node_web -->|"registers editor"| node_profileeditor
node_user -->|"sets reading options"| node_panels
node_web -->|"registers panel service"| node_panels
node_user -->|"sends feedback"| node_feedback
node_feedback -->|"submits message"| node_worker
node_worker -->|"opens issue"| node_github
node_feedback -.->|"opens fallback form"| node_github

click node_web "https://github.com/shoralbrt/transliterator/blob/master/Transliterator.Web/Program.cs"
click node_webpage "https://github.com/shoralbrt/transliterator/blob/master/Transliterator.Web/wwwroot/js/page.js"
click node_cli "https://github.com/shoralbrt/transliterator/blob/master/Transliterator.Cli/CliApp.cs"
click node_normalizer "https://github.com/shoralbrt/transliterator/blob/master/Transliterator.Core/Services/Phonology/ArabicNormalizer.cs"
click node_parser "https://github.com/shoralbrt/transliterator/blob/master/Transliterator.Core/Services/Phonology/ArabicParser.cs"
click node_segments "https://github.com/shoralbrt/transliterator/blob/master/Transliterator.Domain/Phonology/Segment.cs"
click node_rules "https://github.com/shoralbrt/transliterator/blob/master/Transliterator.Core/Services/Rules/RulesService.cs"
click node_waqf "https://github.com/shoralbrt/transliterator/blob/master/Transliterator.Core/Services/Rules/WaqfRule.cs"
click node_article "https://github.com/shoralbrt/transliterator/blob/master/Transliterator.Core/Services/Rules/ArticleRule.cs"
click node_assimilation "https://github.com/shoralbrt/transliterator/blob/master/Transliterator.Core/Services/Rules/AssimilationRule.cs"
click node_nasal "https://github.com/shoralbrt/transliterator/blob/master/Transliterator.Core/Services/Rules/NasalRule.cs"
click node_emphasis "https://github.com/shoralbrt/transliterator/blob/master/Transliterator.Core/Services/Rules/EmphasisRule.cs"
click node_madd "https://github.com/shoralbrt/transliterator/blob/master/Transliterator.Core/Services/Rules/MaddRule.cs"
click node_qalqalah "https://github.com/shoralbrt/transliterator/blob/master/Transliterator.Core/Services/Rules/QalqalahRule.cs"
click node_renderer "https://github.com/shoralbrt/transliterator/blob/master/Transliterator.Core/Services/Phonology/CyrillicRenderer.cs"
click node_service "https://github.com/shoralbrt/transliterator/blob/master/Transliterator.Core/Services/TransliterationService.cs"
click node_reading "https://github.com/shoralbrt/transliterator/blob/master/Transliterator.Domain/Phonology/ReadingOptions.cs"
click node_profilesvc "https://github.com/shoralbrt/transliterator/blob/master/Transliterator.Core/Repositories/UserProfileRepository.cs"
click node_builtins "https://github.com/shoralbrt/transliterator/blob/master/Transliterator.Core/Repositories/EmbeddedProfileRepository.cs"
click node_corpus "https://github.com/shoralbrt/transliterator/blob/master/Transliterator.Core/Repositories/EmbeddedCorpusRepository.cs"
click node_store "https://github.com/shoralbrt/transliterator/blob/master/Transliterator.Web/Storage/LocalStorageStore.cs"
click node_profileeditor "https://github.com/shoralbrt/transliterator/blob/master/Transliterator.Core/Services/ProfileEditor.cs"
click node_panels "https://github.com/shoralbrt/transliterator/blob/master/Transliterator.Core/Services/PagePanels.cs"
click node_feedback "https://github.com/shoralbrt/transliterator/blob/master/Transliterator.Core/Services/FeedbackClient.cs"
click node_worker "https://github.com/shoralbrt/transliterator/blob/master/feedback-worker/src/feedback.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_web,node_webpage,node_cli,node_user toneBlue
class node_normalizer,node_parser,node_segments,node_rules,node_waqf,node_article,node_assimilation,node_nasal,node_emphasis,node_madd,node_qalqalah,node_renderer,node_service,node_reading toneAmber
class node_profilesvc,node_builtins,node_corpus,node_store,node_profileeditor toneMint
class node_panels,node_feedback,node_worker toneRose
class node_github toneIndigo
```

## Components

### User interfaces

- [Web application](https://github.com/shoralbrt/transliterator/blob/master/Transliterator.Web/Program.cs): `Transliterator.Web/Program.cs`
- [Browser page](https://github.com/shoralbrt/transliterator/blob/master/Transliterator.Web/wwwroot/js/page.js): `Transliterator.Web/wwwroot/js/page.js`
- [CLI application](https://github.com/shoralbrt/transliterator/blob/master/Transliterator.Cli/CliApp.cs): `Transliterator.Cli/CliApp.cs`

### Transliteration pipeline

- [Orthography normalization](https://github.com/shoralbrt/transliterator/blob/master/Transliterator.Core/Services/Phonology/ArabicNormalizer.cs): `Transliterator.Core/Services/Phonology/ArabicNormalizer.cs`
- [Arabic segment parser](https://github.com/shoralbrt/transliterator/blob/master/Transliterator.Core/Services/Phonology/ArabicParser.cs): `Transliterator.Core/Services/Phonology/ArabicParser.cs`
- [Phonological segments](https://github.com/shoralbrt/transliterator/blob/master/Transliterator.Domain/Phonology/Segment.cs): `Transliterator.Domain/Phonology/Segment.cs`
- [Tajweed orchestration](https://github.com/shoralbrt/transliterator/blob/master/Transliterator.Core/Services/Rules/RulesService.cs): `Transliterator.Core/Services/Rules/RulesService.cs`
- [Pause and wasl](https://github.com/shoralbrt/transliterator/blob/master/Transliterator.Core/Services/Rules/WaqfRule.cs): `Transliterator.Core/Services/Rules/WaqfRule.cs`
- [Article assimilation](https://github.com/shoralbrt/transliterator/blob/master/Transliterator.Core/Services/Rules/ArticleRule.cs): `Transliterator.Core/Services/Rules/ArticleRule.cs`
- [Consonant assimilation](https://github.com/shoralbrt/transliterator/blob/master/Transliterator.Core/Services/Rules/AssimilationRule.cs): `Transliterator.Core/Services/Rules/AssimilationRule.cs`
- [Nasal rules](https://github.com/shoralbrt/transliterator/blob/master/Transliterator.Core/Services/Rules/NasalRule.cs): `Transliterator.Core/Services/Rules/NasalRule.cs`
- [Emphasis rules](https://github.com/shoralbrt/transliterator/blob/master/Transliterator.Core/Services/Rules/EmphasisRule.cs): `Transliterator.Core/Services/Rules/EmphasisRule.cs`
- [Madd rules](https://github.com/shoralbrt/transliterator/blob/master/Transliterator.Core/Services/Rules/MaddRule.cs): `Transliterator.Core/Services/Rules/MaddRule.cs`
- [Qalqalah rules](https://github.com/shoralbrt/transliterator/blob/master/Transliterator.Core/Services/Rules/QalqalahRule.cs): `Transliterator.Core/Services/Rules/QalqalahRule.cs`
- [Profile renderer](https://github.com/shoralbrt/transliterator/blob/master/Transliterator.Core/Services/Phonology/CyrillicRenderer.cs): `Transliterator.Core/Services/Phonology/CyrillicRenderer.cs`
- [Transliteration service](https://github.com/shoralbrt/transliterator/blob/master/Transliterator.Core/Services/TransliterationService.cs): `Transliterator.Core/Services/TransliterationService.cs`
- [Reading options](https://github.com/shoralbrt/transliterator/blob/master/Transliterator.Domain/Phonology/ReadingOptions.cs): `Transliterator.Domain/Phonology/ReadingOptions.cs`

### Profiles and corpus

- [User profile repository](https://github.com/shoralbrt/transliterator/blob/master/Transliterator.Core/Repositories/UserProfileRepository.cs): `Transliterator.Core/Repositories/UserProfileRepository.cs`
- [Built-in profiles](https://github.com/shoralbrt/transliterator/blob/master/Transliterator.Core/Repositories/EmbeddedProfileRepository.cs): `Transliterator.Core/Repositories/EmbeddedProfileRepository.cs`
- [Surah corpus](https://github.com/shoralbrt/transliterator/blob/master/Transliterator.Core/Repositories/EmbeddedCorpusRepository.cs): `Transliterator.Core/Repositories/EmbeddedCorpusRepository.cs`
- [Browser local storage](https://github.com/shoralbrt/transliterator/blob/master/Transliterator.Web/Storage/LocalStorageStore.cs): `Transliterator.Web/Storage/LocalStorageStore.cs`
- [Profile editor](https://github.com/shoralbrt/transliterator/blob/master/Transliterator.Core/Services/ProfileEditor.cs): `Transliterator.Core/Services/ProfileEditor.cs`

### Browser features

- [Settings panels](https://github.com/shoralbrt/transliterator/blob/master/Transliterator.Core/Services/PagePanels.cs): `Transliterator.Core/Services/PagePanels.cs`
- [Feedback client](https://github.com/shoralbrt/transliterator/blob/master/Transliterator.Core/Services/FeedbackClient.cs): `Transliterator.Core/Services/FeedbackClient.cs`
- [Feedback worker](https://github.com/shoralbrt/transliterator/blob/master/feedback-worker/src/feedback.js): `feedback-worker/src/feedback.js`

### Other components

- **User**
- **GitHub issues**

## Connections

- User → Browser page: enters text (evidence: `README.md`)
- Web application → Transliteration service: registers service (evidence: `Transliterator.Web/Program.cs`)
- Browser page → Transliteration service: requests transliteration (evidence: `README.md`)
- User → CLI application: provides input (evidence: `README.md`)
- CLI application → Transliteration service: requests transliteration (evidence: `Transliterator.Cli/CliServices.cs`)
- Transliteration service → User profile repository: loads profile (evidence: `Transliterator.Core/Services/TransliterationService.cs`)
- Transliteration service → Orthography normalization: normalizes text (evidence: `Transliterator.Core/Services/TransliterationService.cs`)
- Transliteration service → Arabic segment parser: parses text (evidence: `Transliterator.Core/Services/TransliterationService.cs`)
- Arabic segment parser → Phonological segments: creates segments (evidence: `Transliterator.Core/Services/Phonology/ArabicParser.cs`)
- Transliteration service → Tajweed orchestration: applies rules (evidence: `Transliterator.Core/Services/TransliterationService.cs`)
- Tajweed orchestration → Pause and wasl: applies first (evidence: `Transliterator.Core/Services/Rules/RulesService.cs`)
- Tajweed orchestration → Article assimilation: applies (evidence: `Transliterator.Core/Services/Rules/RulesService.cs`)
- Tajweed orchestration → Consonant assimilation: applies (evidence: `Transliterator.Core/Services/Rules/RulesService.cs`)
- Tajweed orchestration → Nasal rules: applies (evidence: `Transliterator.Core/Services/Rules/RulesService.cs`)
- Tajweed orchestration → Emphasis rules: applies (evidence: `Transliterator.Core/Services/Rules/RulesService.cs`)
- Tajweed orchestration → Madd rules: applies (evidence: `Transliterator.Core/Services/Rules/RulesService.cs`)
- Tajweed orchestration → Qalqalah rules: applies (evidence: `Transliterator.Core/Services/Rules/RulesService.cs`)
- Transliteration service → Profile renderer: renders segments (evidence: `Transliterator.Core/Services/TransliterationService.cs`)
- Profile renderer → User profile repository: uses profile (evidence: `README.md`)
- User → Surah corpus: chooses surah (evidence: `README.md`)
- Web application → Surah corpus: registers repository (evidence: `Transliterator.Web/Program.cs`)
- Web application → User profile repository: registers repository (evidence: `Transliterator.Web/Program.cs`)
- User profile repository → Built-in profiles: loads built-ins (evidence: `Transliterator.Core/Repositories/UserProfileRepository.cs`)
- User profile repository → Browser local storage: reads and writes (evidence: `Transliterator.Web/Program.cs`)
- Web application → Profile editor: registers editor (evidence: `Transliterator.Web/Program.cs`)
- User → Settings panels: sets reading options (evidence: `README.md`)
- Web application → Settings panels: registers panel service (evidence: `Transliterator.Web/Program.cs`)
- User → Feedback client: sends feedback (evidence: `README.md`)
- Feedback client → Feedback worker: submits message (evidence: `README.md`)
- Feedback worker → GitHub issues: opens issue (evidence: `README.md`)
- Feedback client → GitHub issues: opens fallback form (evidence: `README.md`)
