# tarekeldeeb/tajweed-embeddings architecture

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

- Interactive diagram: https://gitdiagram.com/tarekeldeeb/tajweed-embeddings
- Repository: https://github.com/tarekeldeeb/tajweed-embeddings

## Overview

This Python library turns Uthmānī Quran text into per-letter Tajwīd-aware vectors, with the original text recoverable from the encoding. Users can embed Quran passages or custom text through the Python API, or inspect results with the CLI; the embedder coordinates text and rule alignment, vector construction, and boundary variants. The README also documents data bootstrapping and rule-span generation. The sampled sources show core encoding, rule indexing, and secondary-variant behavior; links for unsampled generator details are limited to documented capabilities.

Main entry points: [`src/tajweed_embeddings/embedder/tajweed_embedder.py`](https://github.com/tarekeldeeb/tajweed-embeddings/blob/main/src/tajweed_embeddings/embedder/tajweed_embedder.py) (Tajweed embedder), [`src/tajweed_embeddings/embedder/secondary_embedder.py`](https://github.com/tarekeldeeb/tajweed-embeddings/blob/main/src/tajweed_embeddings/embedder/secondary_embedder.py) (Stop/start variants), [`src/tajweed_embeddings/rules_gen/tajweed_classifier.py`](https://github.com/tarekeldeeb/tajweed-embeddings/blob/main/src/tajweed_embeddings/rules_gen/tajweed_classifier.py) (Rule-span classifier), [`src/tajweed_embeddings/util/tanzil_to_json.py`](https://github.com/tarekeldeeb/tajweed-embeddings/blob/main/src/tajweed_embeddings/util/tanzil_to_json.py) (Text to JSON)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User interfaces"]
  node_python_api["Package API<br/>[__init__.py]"]
  node_cli["Inspection CLI<br/>[cli.py]"]
end

subgraph group_encoding["Embedding engine"]
  node_embedder["Tajweed embedder"]
  node_embedding["Embedding result<br/>[embedding.py]"]
  node_haraka["Haraka encoding"]
  node_letters["Letter encoding"]
  node_sifat["Ṣifāt encoding<br/>[sifat_embedder.py]"]
  node_sifat_editor["Contextual ṣifāt<br/>[sifat_editor.py]"]
  node_rules_embedder["Rule and pause encoding"]
  node_secondary["Stop/start variants"]
  node_render["Text rendering and scoring"]
end

subgraph group_data["Quran and rules data"]
  node_quran_data["Quran text data"]
  node_sifat_data["Ṣifāt definitions<br/>[sifat.json]"]
  node_rule_spans["Rule span data"]
  node_normalization["Text normalization<br/>[normalization.py]"]
  node_downloader["Tanzil downloader<br/>[quran_download.py]"]
  node_converter["Text to JSON<br/>[tanzil_to_json.py]"]
end

subgraph group_generation["Rule generation"]
  node_classifier["Rule-span classifier"]
  node_rule_trees["Rule decision trees"]
  node_tree_utils["Tree utilities<br/>[tree.py]"]
end

node_python_user(("Python caller"))
node_cli_user(("CLI user"))
node_tanzil(("Tanzil text source"))

node_python_user -->|"calls"| node_python_api
node_python_api -->|"constructs"| node_embedder
node_cli_user -->|"runs"| node_cli
node_cli -->|"requests encoding"| node_embedder
node_embedder -->|"loads text"| node_quran_data
node_embedder -->|"loads spans"| node_rule_spans
node_embedder -->|"loads definitions"| node_sifat_data
node_embedder -->|"normalizes text"| node_normalization
node_embedder -->|"encodes harakāt"| node_haraka
node_embedder -->|"encodes letters"| node_letters
node_embedder -->|"encodes ṣifāt"| node_sifat
node_embedder -->|"applies spans"| node_rules_embedder
node_embedder -->|"builds variants"| node_secondary
node_embedder -->|"assembles vectors"| node_embedding
node_embedder -->|"renders and scores"| node_render
node_secondary -->|"updates states"| node_haraka
node_secondary -->|"re-encodes traits"| node_sifat
node_secondary -->|"edits context"| node_sifat_editor
node_downloader -.->|"fetches text"| node_tanzil
node_embedder -.->|"bootstraps data"| node_downloader
node_converter -->|"normalizes input"| node_normalization
node_converter -->|"writes JSON"| node_quran_data
node_classifier -->|"loads trees"| node_rule_trees
node_classifier -->|"uses tree helpers"| node_tree_utils
node_classifier -->|"generates spans"| node_rule_spans

click node_python_api "https://github.com/tarekeldeeb/tajweed-embeddings/blob/main/src/tajweed_embeddings/__init__.py"
click node_cli "https://github.com/tarekeldeeb/tajweed-embeddings/blob/main/src/tajweed_embeddings/embedder/cli.py"
click node_embedder "https://github.com/tarekeldeeb/tajweed-embeddings/blob/main/src/tajweed_embeddings/embedder/tajweed_embedder.py"
click node_embedding "https://github.com/tarekeldeeb/tajweed-embeddings/blob/main/src/tajweed_embeddings/embedder/embedding.py"
click node_haraka "https://github.com/tarekeldeeb/tajweed-embeddings/blob/main/src/tajweed_embeddings/embedder/harakat_embedder.py"
click node_letters "https://github.com/tarekeldeeb/tajweed-embeddings/blob/main/src/tajweed_embeddings/embedder/letters_embedder.py"
click node_sifat "https://github.com/tarekeldeeb/tajweed-embeddings/blob/main/src/tajweed_embeddings/embedder/sifat_embedder.py"
click node_sifat_editor "https://github.com/tarekeldeeb/tajweed-embeddings/blob/main/src/tajweed_embeddings/embedder/sifat_editor.py"
click node_rules_embedder "https://github.com/tarekeldeeb/tajweed-embeddings/blob/main/src/tajweed_embeddings/embedder/tajweed_rules_embedder.py"
click node_secondary "https://github.com/tarekeldeeb/tajweed-embeddings/blob/main/src/tajweed_embeddings/embedder/secondary_embedder.py"
click node_render "https://github.com/tarekeldeeb/tajweed-embeddings/blob/main/src/tajweed_embeddings/embedder/tajweed_embedder.py"
click node_quran_data "https://github.com/tarekeldeeb/tajweed-embeddings/tree/main/src/tajweed_embeddings/data"
click node_sifat_data "https://github.com/tarekeldeeb/tajweed-embeddings/blob/main/src/tajweed_embeddings/data/sifat.json"
click node_rule_spans "https://github.com/tarekeldeeb/tajweed-embeddings/tree/main/src/tajweed_embeddings/data"
click node_normalization "https://github.com/tarekeldeeb/tajweed-embeddings/blob/main/src/tajweed_embeddings/util/normalization.py"
click node_downloader "https://github.com/tarekeldeeb/tajweed-embeddings/blob/main/src/tajweed_embeddings/util/quran_download.py"
click node_converter "https://github.com/tarekeldeeb/tajweed-embeddings/blob/main/src/tajweed_embeddings/util/tanzil_to_json.py"
click node_classifier "https://github.com/tarekeldeeb/tajweed-embeddings/blob/main/src/tajweed_embeddings/rules_gen/tajweed_classifier.py"
click node_rule_trees "https://github.com/tarekeldeeb/tajweed-embeddings/tree/main/src/tajweed_embeddings/rules_gen/rule_trees"
click node_tree_utils "https://github.com/tarekeldeeb/tajweed-embeddings/blob/main/src/tajweed_embeddings/rules_gen/tree.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_python_api,node_cli,node_cli_user toneBlue
class node_embedder,node_embedding,node_haraka,node_letters,node_sifat,node_sifat_editor,node_rules_embedder,node_secondary,node_render toneAmber
class node_quran_data,node_sifat_data,node_rule_spans,node_normalization,node_downloader,node_converter toneMint
class node_classifier,node_rule_trees,node_tree_utils toneRose
class node_python_user,node_tanzil toneIndigo
```

## Components

### User interfaces

- [Package API](https://github.com/tarekeldeeb/tajweed-embeddings/blob/main/src/tajweed_embeddings/__init__.py): `src/tajweed_embeddings/__init__.py`
- [Inspection CLI](https://github.com/tarekeldeeb/tajweed-embeddings/blob/main/src/tajweed_embeddings/embedder/cli.py): `src/tajweed_embeddings/embedder/cli.py`

### Embedding engine

- [Tajweed embedder](https://github.com/tarekeldeeb/tajweed-embeddings/blob/main/src/tajweed_embeddings/embedder/tajweed_embedder.py): `src/tajweed_embeddings/embedder/tajweed_embedder.py`
- [Embedding result](https://github.com/tarekeldeeb/tajweed-embeddings/blob/main/src/tajweed_embeddings/embedder/embedding.py): `src/tajweed_embeddings/embedder/embedding.py`
- [Haraka encoding](https://github.com/tarekeldeeb/tajweed-embeddings/blob/main/src/tajweed_embeddings/embedder/harakat_embedder.py): `src/tajweed_embeddings/embedder/harakat_embedder.py`
- [Letter encoding](https://github.com/tarekeldeeb/tajweed-embeddings/blob/main/src/tajweed_embeddings/embedder/letters_embedder.py): `src/tajweed_embeddings/embedder/letters_embedder.py`
- [Ṣifāt encoding](https://github.com/tarekeldeeb/tajweed-embeddings/blob/main/src/tajweed_embeddings/embedder/sifat_embedder.py): `src/tajweed_embeddings/embedder/sifat_embedder.py`
- [Contextual ṣifāt](https://github.com/tarekeldeeb/tajweed-embeddings/blob/main/src/tajweed_embeddings/embedder/sifat_editor.py): `src/tajweed_embeddings/embedder/sifat_editor.py`
- [Rule and pause encoding](https://github.com/tarekeldeeb/tajweed-embeddings/blob/main/src/tajweed_embeddings/embedder/tajweed_rules_embedder.py): `src/tajweed_embeddings/embedder/tajweed_rules_embedder.py`
- [Stop/start variants](https://github.com/tarekeldeeb/tajweed-embeddings/blob/main/src/tajweed_embeddings/embedder/secondary_embedder.py): `src/tajweed_embeddings/embedder/secondary_embedder.py`
- [Text rendering and scoring](https://github.com/tarekeldeeb/tajweed-embeddings/blob/main/src/tajweed_embeddings/embedder/tajweed_embedder.py): `src/tajweed_embeddings/embedder/tajweed_embedder.py`

### Quran and rules data

- [Quran text data](https://github.com/tarekeldeeb/tajweed-embeddings/tree/main/src/tajweed_embeddings/data): `src/tajweed_embeddings/data`
- [Ṣifāt definitions](https://github.com/tarekeldeeb/tajweed-embeddings/blob/main/src/tajweed_embeddings/data/sifat.json): `src/tajweed_embeddings/data/sifat.json`
- [Rule span data](https://github.com/tarekeldeeb/tajweed-embeddings/tree/main/src/tajweed_embeddings/data): `src/tajweed_embeddings/data`
- [Text normalization](https://github.com/tarekeldeeb/tajweed-embeddings/blob/main/src/tajweed_embeddings/util/normalization.py): `src/tajweed_embeddings/util/normalization.py`
- [Tanzil downloader](https://github.com/tarekeldeeb/tajweed-embeddings/blob/main/src/tajweed_embeddings/util/quran_download.py): `src/tajweed_embeddings/util/quran_download.py`
- [Text to JSON](https://github.com/tarekeldeeb/tajweed-embeddings/blob/main/src/tajweed_embeddings/util/tanzil_to_json.py): `src/tajweed_embeddings/util/tanzil_to_json.py`

### Rule generation

- [Rule-span classifier](https://github.com/tarekeldeeb/tajweed-embeddings/blob/main/src/tajweed_embeddings/rules_gen/tajweed_classifier.py): `src/tajweed_embeddings/rules_gen/tajweed_classifier.py`
- [Rule decision trees](https://github.com/tarekeldeeb/tajweed-embeddings/tree/main/src/tajweed_embeddings/rules_gen/rule_trees): `src/tajweed_embeddings/rules_gen/rule_trees`
- [Tree utilities](https://github.com/tarekeldeeb/tajweed-embeddings/blob/main/src/tajweed_embeddings/rules_gen/tree.py): `src/tajweed_embeddings/rules_gen/tree.py`

### Other components

- **Python caller**
- **CLI user**
- **Tanzil text source**

## Connections

- Python caller → Package API: calls
- Package API → Tajweed embedder: constructs
- CLI user → Inspection CLI: runs
- Inspection CLI → Tajweed embedder: requests encoding
- Tajweed embedder → Quran text data: loads text
- Tajweed embedder → Rule span data: loads spans
- Tajweed embedder → Ṣifāt definitions: loads definitions
- Tajweed embedder → Text normalization: normalizes text
- Tajweed embedder → Haraka encoding: encodes harakāt
- Tajweed embedder → Letter encoding: encodes letters
- Tajweed embedder → Ṣifāt encoding: encodes ṣifāt
- Tajweed embedder → Rule and pause encoding: applies spans
- Tajweed embedder → Stop/start variants: builds variants
- Tajweed embedder → Embedding result: assembles vectors
- Tajweed embedder → Text rendering and scoring: renders and scores
- Stop/start variants → Haraka encoding: updates states
- Stop/start variants → Ṣifāt encoding: re-encodes traits
- Stop/start variants → Contextual ṣifāt: edits context
- Tanzil downloader → Tanzil text source: fetches text
- Tajweed embedder → Tanzil downloader: bootstraps data
- Text to JSON → Text normalization: normalizes input
- Text to JSON → Quran text data: writes JSON
- Rule-span classifier → Rule decision trees: loads trees
- Rule-span classifier → Tree utilities: uses tree helpers
- Rule-span classifier → Rule span data: generates spans