📖 Ahlul Bayt Treasures

A clean, structured, and multi-format dataset of Islamic Duas (supplications) from the Ahlul Bayt designed for developers, researchers, and open-source projects.

This repository provides dependency-free, pre-compiled data files in 9 different formats, covering everything from modern web apps and mobile platforms to embedded IoT devices and data science pipelines.

Key Features:

• 🚫 Zero Bloat: No YouTube links, MP3s, or app-specific UI logic. Just pure text data.
• 🧠 Smart UI Hints: Pre-calculated show_id fields handle complex edge cases (like hiding verse numbers for Bismillah or Instructions) so you don't have to.
• ⚡ Lazy-Loading Ready: Includes lightweight "Names Only" index files for instant Master-Detail UI rendering.
• 🌍 Universal Compatibility: Native support for Web, iOS, Android, C++, Python, and Embedded Systems.

---

📂 Available Formats

Every format is provided in two variations: Full Data (complete Arabic, Translation, Transliteration, and instructions) and Names Only (a lightweight array/map for home screen lists).

Format	Full Data File	Names Only File	Best Use Case
JSON	duas_data.json	duas_names.json	Web apps, Node.js, React, Vue, general API usage.
JSONL	duas_data.jsonl	duas_names.jsonl	Streaming large datasets, React Native, low-memory environments.
SQLite	duas_data.sqlite	duas_names.sqlite	iOS/Android apps, offline-first architectures, relational queries.
XML	duas_data.xml	duas_names.xml	Enterprise systems, legacy Java/C# apps, XSLT transformations.
CSV	duas_data.csv	duas_names.csv	Data analysis, Excel, Google Sheets, bulk database imports. (All fields are quoted for safety.)
YAML	duas_data.yaml	duas_names.yaml	Static site generators (Hugo, Jekyll, Next.js), config files.
Python	duas_data.py	duas_names.py	Django, Flask, FastAPI, Data Science, direct memory import.
C++	duas_data_u8.h (UTF‑8 safe) duas_data_plain.h (plain literals)	duas_names_u8.h duas_names_plain.h	IoT (Arduino, ESP32), Embedded Systems, Qt, Native Desktop. Choose _u8 for portable UTF‑8 (C++11/14/17) or _plain if your compiler uses UTF‑8 execution charset.
MessagePack	duas_data.msgpack	duas_names.msgpack	High-performance mobile, gaming engines, low-bandwidth networks.

---

🏗️ Data Schema & Architecture

1. The Full Dua Object

Each Dua contains an array of rows. A row represents a single line/verse of the supplication.

{
  "id": 1,
  "name": "Dua for the Beginning of Ramadhan",
  "rows": [
    {
      "index": 1,
      "show_id": "",
      "arabic": "بِسْمِ اللَّهِ الرَّحْمَٰنِ الرَّحِيمِ",
      "translation": "In the name of Allah, the Beneficent, the Merciful.",
      "transliteration": "bismillāhir raḥmānir raḥīm",
      "instruction": "",
      "title": ""
    },
    {
      "index": 2,
      "show_id": "1",
      "arabic": "اللَّهُمَّ وَقَدْ دَخَلَ عَلَيْنا...",
      "translation": "O Allah, the month of Ramadhan has arrived upon us...",
      "transliteration": "allāhumma waqad dakhala `alaynā...",
      "instruction": "",
      "title": ""
    },
    {
      "index": 3,
      "show_id": "",
      "arabic": "",
      "translation": "",
      "transliteration": "",
      "instruction": "Repeat 3 times",
      "title": ""
    }
  ]
}

2. Understanding the Fields (Crucial for UI Rendering)

To save developers from writing complex parsing logic, the dataset includes pre-calculated UI hints:

• index (Integer): The absolute sequential row number (1, 2, 3...).
• show_id (String): The Verse Number.
  • If it has a value (e.g., "1", "2"), display it next to the Arabic text.
  • If it is empty (""), hide the verse number. This automatically handles edge cases like the opening Bismillah, Allahumma salli..., or non-recited instructions.
• instruction (String): Non-recited guidance (e.g., "Repeat 3 times", "Say 7 times"). If this field is populated, the UI should render it as a distinct badge or divider, not as recited text.
• title (String): Sub-headings within a longer Dua.

3. The Names List (Master-Detail Pattern)

The duas_names.* files are optimized for Lazy Loading. Instead of downloading a 5MB JSON file just to show a list of titles on a home screen, fetch the tiny Names file (a few KB).

Note: The Names array is 1-indexed to match the original source IDs. Index 0 is null or empty. If a Dua was intentionally excluded from this open-source release, its index will remain null to prevent "off-by-one" alignment errors in your code.

// duas_names.json
[
  null, 
  "Dua for the Beginning of Ramadhan",
  "Dua for the Sighting of the Moon",
  ...
]

---

🚀 Integration Guides

Web / React Native (Lazy Loading with JSON)

// 1. Fetch the lightweight names list for the Home Screen
const names = await fetch('/duas_names.json').then(res => res.json());

function HomeScreen() {
  return names.map((title, index) => (
    // 2. Render the list instantly
    <ListItem key={index} title={title} onPress={() => loadFullDua(index)} />
  ));
}

// 3. Only fetch the heavy Arabic/Translation data when the user taps a title
async function loadFullDua(id) {
  const fullData = await fetch('/duas_data.json').then(res => res.json());
  const dua = fullData.duas.find(d => d.id === id);
  navigateToDetailScreen(dua);
}

Mobile / Streaming (JSONL)

Use JSONL to stream the dataset line-by-line, preventing memory spikes on low-end Android/iOS devices.

const rl = readline.createInterface({ input: fs.createReadStream('duas_data.jsonl') });
for await (const line of rl) {
  const dua = JSON.parse(line);
  // Render progressively as data arrives
}

Embedded / IoT (C++ Header)

For Arduino, ESP32, or native desktop apps, include the appropriate header. Choose the _u8 version for portable UTF‑8 or _plain if your compiler is set to UTF‑8.

#include "duas_data_u8.h"   // or "duas_data_plain.h"
#include <iostream>

void setup() {
    // Access data directly from memory
    std::string firstDuaName = DuasData::DUAS[0].name; 
    std::string arabicText = DuasData::DUAS[0].rows[0].arabic;
}

Backend / Python

from duas_data import DUAS

for dua in DUAS:
    print(f"Processing: {dua['name']}")
    for row in dua['rows']:
        if row['instruction']:
            print(f"UI Hint: {row['instruction']}")

---

🔄 Versioning & Updates

This dataset follows Semantic Versioning (SemVer).

• Major (x.0.0): Breaking changes to the JSON schema or field names.
• Minor (0.x.0): Addition of new Duas or new languages.
• Patch (0.0.x): Typo fixes in Arabic, Translation, or Transliteration.

Checking for updates programmatically: Read the VERSION file located at the root of this repository, or check the metadata.version object inside the JSON/XML/MsgPack files.

---

⚖️ License & Attribution

Public Domain You are free to use, modify, distribute, and monetize this data in any application (commercial or non-commercial) without restriction.

While attribution is not legally required, a small "Powered by Ahlul Bayt Treasures" in your app's About section is deeply appreciated and helps sustain the open-source Islamic tech ecosystem.

---

🤝 Contributing / Reporting Errors

Found a typo in the Arabic text or a mistranslation? Please open an Issue on this repository with the Dua ID, Row Index, and the correction. Because this is a static data repository, fixes are merged, the build script is re-run, and a new Patch version is tagged automatically.