Skip to content

README.md

Latest commit

 

History

History
184 lines (146 loc) · 7.79 KB

README.md

File metadata and controls

184 lines (146 loc) · 7.79 KB
Raw

📖 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.