### Start QUL Application Development Server

Source: https://github.com/tarteelai/quranic-universal-library/blob/main/README.md

Launches the Quran Universal Library development server using the bin/dev script. This typically starts Rails server and frontend build tools. Requires successful completion of all prior setup steps.

```bash
bin/dev
```

--------------------------------

### Git Contribution Workflow for QUL

Source: https://github.com/tarteelai/quranic-universal-library/blob/main/README.md

Complete Git workflow for contributing to QUL. Includes cloning a personal fork, creating a feature branch, and pushing changes. Requires Git, a GitHub account, and a forked repository. The commands demonstrate standard Git operations for feature development.

```bash
   git clone https://github.com/your_username/quranic-universal-library.git
```

```bash
     git checkout -b making-qul
```

```bash
git add .
git commit -m "Add a brief description of your changes"
git push origin your-feature-branch
```

--------------------------------

### Run Rails Database Migrations and Seeding

Source: https://github.com/tarteelai/quranic-universal-library/blob/main/README.md

Executes Rails database migrations and seeds initial data for the quran_community_tarteel database. The migrate command appears twice, possibly for multiple databases. Requires Rails environment configuration and database connections.

```ruby
rails db:migrate
rails db:migrate
rails db:seed
```

--------------------------------

### Restore quran_dev Database using SQL Dump

Source: https://github.com/tarteelai/quranic-universal-library/blob/main/README.md

This snippet demonstrates how to restore the `quran_dev` database from a SQL dump file. Ensure you have the SQL dump file downloaded and `psql` installed and configured. This method is suitable for initial setup or when a plain SQL format is preferred.

```bash
psql quran_dev < "path to sql dump file"
```

```bash
psql -U postgres -d quran_dev -f path/to/quran_dev.sql
```

--------------------------------

### Launch the QUL Application

Source: https://github.com/tarteelai/quranic-universal-library/blob/main/README.md

This command starts the Quranic Universal Library (QUL) application. After setting up the database and running migrations, execute this command to run the application locally. The application will typically be accessible via `http://localhost:3000`.

```bash
bin/dev
```

--------------------------------

### Get Chapter Details

Source: https://context7.com/tarteelai/quranic-universal-library/llms.txt

Retrieve detailed information about a specific chapter including all available scripts and metadata.

```APIDOC
## GET /api/v1/chapters/{id}

### Description
Retrieve detailed information about a specific chapter including all available scripts and metadata.

### Method
GET

### Endpoint
/api/v1/chapters/{id}

### Parameters
#### Path Parameters
- **id** (integer) - Required - The ID of the chapter to retrieve.

#### Query Parameters
None

### Request Example
```bash
curl -X GET "https://qul.tarteel.ai/api/v1/chapters/1" \
  -H "Accept: application/json"
```

### Response
#### Success Response (200)
- **chapter** (object) - An object containing the chapter's details.
  - **id** (integer) - The unique identifier for the chapter.
  - **chapter_number** (integer) - The sequential number of the chapter.
  - **name_simple** (string) - The simple name of the chapter.
  - **name_complex** (string) - The complex name of the chapter.
  - **name_arabic** (string) - The Arabic name of the chapter.
  - **verses_count** (integer) - The number of verses in the chapter.
  - **pages** (array) - An array of page numbers where the chapter appears.
  - **revelation_place** (string) - The place of revelation (Mecca or Medina).
  - **revelation_order** (integer) - The order of revelation.
  - **bismillah_pre** (boolean) - Indicates if Bismillah is present before the chapter.

#### Response Example
```json
{
  "chapter": {
    "id": 1,
    "chapter_number": 1,
    "name_simple": "Al-Fatihah",
    "name_complex": "Al-Fātiĥah",
    "name_arabic": "الفاتحة",
    "verses_count": 7,
    "pages": [1, 1],
    "revelation_place": "makkah",
    "revelation_order": 5,
    "bismillah_pre": true
  }
}
```
```

--------------------------------

### Get All Chapters

Source: https://context7.com/tarteelai/quranic-universal-library/llms.txt

Retrieve a list of all 114 chapters (Surahs) in the Quran with their metadata including names, revelation order, and verse counts.

```APIDOC
## GET /api/v1/chapters

### Description
Retrieve a list of all 114 chapters (Surahs) in the Quran with their metadata including names, revelation order, and verse counts.

### Method
GET

### Endpoint
/api/v1/chapters

### Parameters
#### Query Parameters
None

### Request Example
```bash
curl -X GET "https://qul.tarteel.ai/api/v1/chapters" \
  -H "Accept: application/json"
```

### Response
#### Success Response (200)
- **chapters** (array) - An array of chapter objects.
  - **id** (integer) - The unique identifier for the chapter.
  - **chapter_number** (integer) - The sequential number of the chapter.
  - **name_simple** (string) - The simple name of the chapter.
  - **name_arabic** (string) - The Arabic name of the chapter.
  - **verses_count** (integer) - The number of verses in the chapter.
  - **revelation_place** (string) - The place of revelation (Mecca or Medina).
  - **revelation_order** (integer) - The order of revelation.

#### Response Example
```json
{
  "chapters": [
    {
      "id": 1,
      "chapter_number": 1,
      "name_simple": "Al-Fatihah",
      "name_arabic": "الفاتحة",
      "verses_count": 7,
      "revelation_place": "makkah",
      "revelation_order": 5
    },
    {
      "id": 2,
      "chapter_number": 2,
      "name_simple": "Al-Baqarah",
      "name_arabic": "البقرة",
      "verses_count": 286,
      "revelation_place": "madinah",
      "revelation_order": 87
    }
  ]
}
```
```

--------------------------------

### Manage Quranic Translations with Drafts and Proofreading (Ruby)

Source: https://context7.com/tarteelai/quranic-universal-library/llms.txt

Code examples for handling Quranic translations, including fetching translations for a verse, retrieving a specific translation by resource and verse, searching translations by text, creating draft translations for proofreading, and updating footnote counts. This facilitates translation management and quality control.

```ruby
# Get translations for a specific verse
translations = Translation
  .where(verse_key: '1:1')
  .includes(:language, :resource_content)

translations.each do |trans|
  puts "#{trans.resource_name} (#{trans.language_name}):"
  puts trans.text
  puts "Has footnotes: #{trans.footnotes_count > 0}"
end

# Get translation by resource and verse
translation = Translation.find_by(
  verse_key: '2:255',
  resource_content_id: 131 # Clear Quran
)

# Search translations by text
search_results = Translation
  .text_search('light')
  .includes(:verse)
  .limit(20)

search_results.each do |result|
  puts "#{result.verse_key}: #{result.text}"
end

# Create a draft translation for proofreading
translation = Translation.find_by(verse_key: '1:1', resource_content_id: 131)
draft = translation.save_suggestions(
  { draft_text: "Updated translation text..." },
  current_user
)
puts "Draft created: #{draft.need_review}"

# Update footnote counts
translation.update_footnote_count
```

--------------------------------

### Run All Cypress Tests (Headless)

Source: https://github.com/tarteelai/quranic-universal-library/blob/main/scripts/cypress-e2e/readme.md

Executes all Cypress tests in headless mode, suitable for CI/CD pipelines. Ensure Cypress is installed in the project before running.

```bash
npx cypress run
```

--------------------------------

### Open Cypress Test Runner

Source: https://github.com/tarteelai/quranic-universal-library/blob/main/scripts/cypress-e2e/readme.md

Opens the Cypress Test Runner GUI for interactive test execution and debugging. This command requires Cypress to be installed in the project.

```bash
npx cypress open
```

--------------------------------

### Get Available Languages - cURL

Source: https://context7.com/tarteelai/quranic-universal-library/llms.txt

Lists all languages that have available translations or tafsirs in the system. This endpoint helps in discovering the linguistic diversity of the Quranic content available.

```bash
curl -X GET "https://qul.tarteel.ai/api/v1/resources/languages" \
  -H "Accept: application/json"
```

--------------------------------

### Get Chapter Data with Related Information (Ruby)

Source: https://context7.com/tarteelai/quranic-universal-library/llms.txt

Retrieves a specific chapter along with its associated translated names, chapter information, and verses. This is useful for displaying comprehensive chapter details.

```ruby
chapter = Chapter
  .includes(:verses, :translated_names, :chapter_infos)
  .find_by(chapter_number: 1)
```

--------------------------------

### Get Available Languages

Source: https://context7.com/tarteelai/quranic-universal-library/llms.txt

Lists all languages for which translations or tafsirs are available in the system. This endpoint helps users discover the range of linguistic resources offered.

```APIDOC
## GET /api/v1/resources/languages

### Description
List all languages with available translations or tafsirs.

### Method
GET

### Endpoint
/api/v1/resources/languages

### Parameters

#### Query Parameters
None

### Request Example
```bash
curl -X GET "https://qul.tarteel.ai/api/v1/resources/languages" \
  -H "Accept: application/json"
```

### Response
#### Success Response (200)
- **languages** (array) - An array of language objects.
  - **id** (integer) - Unique identifier for the language.
  - **name** (string) - The name of the language.
  - **iso_code** (string) - The ISO 639-1 code for the language (e.g., "en").
  - **native_name** (string) - The native name of the language.
  - **direction** (string) - The text direction (e.g., "ltr" for left-to-right, "rtl" for right-to-left).
  - **translations_count** (integer) - The number of available translations for this language.
  - **tafsirs_count** (integer) - The number of available tafsirs for this language.

#### Response Example
```json
{
  "languages": [
    {
      "id": 38,
      "name": "English",
      "iso_code": "en",
      "native_name": "English",
      "direction": "ltr",
      "translations_count": 42,
      "tafsirs_count": 12
    },
    {
      "id": 174,
      "name": "Urdu",
      "iso_code": "ur",
      "native_name": "اردو",
      "direction": "rtl",
      "translations_count": 15,
      "tafsirs_count": 8
    }
  ]
}
```
```

--------------------------------

### Run Specific Cypress Spec File (Headless)

Source: https://github.com/tarteelai/quranic-universal-library/blob/main/scripts/cypress-e2e/readme.md

Executes a specific Cypress test file in headless mode. Replace '<spec-file>.cy.js' with the actual path to your test file. Requires Cypress installation.

```bash
npx cypress run --spec "cypress/e2e/Tests/<spec-file>.cy.js"
```

--------------------------------

### Get Available Audio Recitations (Surah by Surah)

Source: https://context7.com/tarteelai/quranic-universal-library/llms.txt

Lists all available Surah-based (chapter by chapter) audio recitations with reciter information. This endpoint is useful for discovering different recitation options available for the Quran.

```APIDOC
## GET /api/v1/audio/surah_recitations

### Description
Lists all available Surah-based (chapter by chapter) audio recitations with reciter information.

### Method
GET

### Endpoint
/api/v1/audio/surah_recitations

### Parameters

#### Query Parameters
None

### Request Example
```bash
curl -X GET "https://qul.tarteel.ai/api/v1/audio/surah_recitations" \
  -H "Accept: application/json"
```

### Response
#### Success Response (200)
- **recitations** (array) - An array of recitation objects.
  - **id** (integer) - Unique identifier for the recitation.
  - **name** (string) - The name of the reciter.
  - **arabic_name** (string) - The Arabic name of the reciter.
  - **reciter_id** (integer) - The unique identifier for the reciter.
  - **style** (string) - The style of recitation (e.g., "Murattal").
  - **approved** (boolean) - Indicates if the recitation is approved.
  - **format** (string) - The audio file format (e.g., "mp3").
  - **files_count** (integer) - The total number of audio files available for this recitation.
  - **segments_count** (integer) - The total number of audio segments available.

#### Response Example
```json
{
  "recitations": [
    {
      "id": 1,
      "name": "Alafasy",
      "arabic_name": "مشاري بن راشد العفاسي",
      "reciter_id": 7,
      "style": "Murattal",
      "approved": true,
      "format": "mp3",
      "files_count": 114,
      "segments_count": 6236
    },
    {
      "id": 2,
      "name": "Abdul Basit (Murattal)",
      "reciter_id": 1,
      "style": "Murattal",
      "approved": true,
      "format": "mp3",
      "files_count": 114
    }
  ]
}
```
```

--------------------------------

### Get All Available Translations - cURL

Source: https://context7.com/tarteelai/quranic-universal-library/llms.txt

Retrieves metadata for all available translation resources in the system, including the translation name, author, language, and record count. Useful for listing or selecting translations.

```bash
curl -X GET "https://qul.tarteel.ai/api/v1/resources/translations" \
  -H "Accept: application/json"
```

--------------------------------

### Get Available Audio Recitations (Surah by Surah) - cURL

Source: https://context7.com/tarteelai/quranic-universal-library/llms.txt

Lists all available Surah-based (chapter by chapter) audio recitations, including reciter information. This endpoint is useful for discovering different recitation options and their metadata.

```bash
curl -X GET "https://qul.tarteel.ai/api/v1/audio/surah_recitations" \
  -H "Accept: application/json"
```

--------------------------------

### Parse and Validate Audio Segment Timestamps

Source: https://context7.com/tarteelai/quranic-universal-library/llms.txt

Provides examples for parsing audio segment data, including word-level timestamps and text. It also covers batch importing segments for entire recitations and validating the imported data.

```ruby
# Parse segment data from file
parser = AudioSegmentParser.new(
  recitation_id: 1,
  chapter_id: 1
)

# Process segments with validation
segments_data = File.read('segments/001.json')
parsed = parser.parse(segments_data)

parsed.each do |segment|
  verse_key = segment[:verse_key]
  timestamp_from = segment[:timestamp_from]
  timestamp_to = segment[:timestamp_to]

  segment[:segments].each do |word_segment|
    word_position, from, to, text = word_segment
    puts "#{verse_key} word #{word_position}: #{from}-#{to}ms (#{text})"
  end
end

# Batch import segments for entire recitation
batch_parser = BatchAudioSegmentParser.new(recitation_id: 1)
batch_parser.import_all_chapters do |progress|
  puts "Imported chapter #{progress[:chapter]} - #{progress[:segments]} segments"
end

# Validate imported segments
recitation = Audio::Recitation.find(1)
validation_issues = recitation.validate_segments_data
validation_issues.each do |issue|
  puts "#{issue[:severity]}: #{issue[:text]}"
end
```

--------------------------------

### Get All Quran Chapters API Request

Source: https://context7.com/tarteelai/quranic-universal-library/llms.txt

Retrieves a list of all 114 Quran chapters (Surahs) along with their metadata such as names, revelation order, and verse counts. This endpoint is useful for an overview of the Quranic structure.

```bash
curl -X GET "https://qul.tarteel.ai/api/v1/chapters" \
  -H "Accept: application/json"
```

--------------------------------

### Get Translations by Range

Source: https://context7.com/tarteelai/quranic-universal-library/llms.txt

Retrieve translations for a range of verses, supporting both verse keys and sequential IDs.

```APIDOC
## GET /api/v1/translations/{resource_content_id}/by_range

### Description
Retrieve translations for a range of verses, supporting both verse keys and sequential IDs.

### Method
GET

### Endpoint
/api/v1/translations/{resource_content_id}/by_range

### Parameters
#### Path Parameters
- **resource_content_id** (integer) - Required - The ID of the translation resource.

#### Query Parameters
- **from** (string) - Optional - The starting verse key for the range (e.g., '1:1').
- **to** (string) - Optional - The ending verse key for the range (e.g., '1:7').
- **ayah_keys** (string) - Optional - A comma-separated string of verse keys or ranges (e.g., '1:1-1:3,2:1,2:5-2:10').

### Request Example
```bash
# Using verse keys range
curl -X GET "https://qul.tarteel.ai/api/v1/translations/131/by_range" \
  -H "Accept: application/json" \
  -d "from=1:1" \
  -d "to=1:7"

# Using comma-separated ayah keys with ranges
curl -X GET "https://qul.tarteel.ai/api/v1/translations/131/by_range" \
  -H "Accept: application/json" \
  -d "ayah_keys=1:1-1:3,2:1,2:5-2:10"
```

### Response
#### Success Response (200)
- **translations** (array) - An array of translation objects.
  - **id** (integer) - The unique identifier for the translation.
  - **resource_content_id** (integer) - The ID of the translation resource.
  - **text** (string) - The translated text of the verse.
  - **verse_key** (string) - The verse key (e.g., '1:1').
  - **verse_number** (integer) - The number of the verse.
  - **chapter_id** (integer) - The ID of the chapter the verse belongs to.
- **meta** (object) - Metadata about the response.
  - **total_count** (integer) - The total number of translations returned.
  - **current_page** (integer) - The current page number of the results.

#### Response Example
```json
{
  "translations": [
    {
      "id": 1,
      "resource_content_id": 131,
      "text": "In the Name of Allah—the Most Compassionate, Most Merciful.",
      "verse_key": "1:1",
      "verse_number": 1,
      "chapter_id": 1
    },
    {
      "id": 2,
      "resource_content_id": 131,
      "text": "All praise is for Allah—Lord of all worlds,",
      "verse_key": "1:2",
      "verse_number": 2,
      "chapter_id": 1
    }
  ],
  "meta": {
    "total_count": 7,
    "current_page": 1
  }
}
```
```

--------------------------------

### Clone QUL Repository Fork

Source: https://github.com/tarteelai/quranic-universal-library/blob/main/README.md

This Git command clones your forked copy of the Quranic Universal Library repository to your local machine. Replace `your_username` with your GitHub username. This is the first step in contributing to the project.

```bash
git clone https://github.com/your_username/quranic-universal-library.git
```

--------------------------------

### JavaScript: Initialize WaveSurfer.js with Plugins

Source: https://github.com/tarteelai/quranic-universal-library/blob/main/public/compare-audio.html

Initializes two WaveSurfer.js instances for audio comparison. Each instance is configured with common plugins like Timeline, Hover, and Zoom, along with custom Regions for interactive selection. The `container`, `waveColor`, and `progressColor` are set for visual distinction.

```javascript
import WaveSurfer from 'https://cdnjs.cloudflare.com/ajax/libs/wavesurfer.js/7.8.14/wavesurfer.esm.min.js';
import Timeline from 'https://cdnjs.cloudflare.com/ajax/libs/wavesurfer.js/7.8.14/plugins/timeline.esm.min.js';
import Regions from 'https://cdnjs.cloudflare.com/ajax/libs/wavesurfer.js/7.8.14/plugins/regions.esm.min.js';
import Hover from 'https://cdnjs.cloudflare.com/ajax/libs/wavesurfer.js/7.8.14/plugins/hover.esm.min.js';
import Zoom from 'https://cdnjs.cloudflare.com/ajax/libs/wavesurfer.js/7.8.14/plugins/zoom.esm.min.js';

document.addEventListener('DOMContentLoaded', () => {
    const audio1Regions = Regions.create()
    const audio2Regions = Regions.create()
    const wavesurfer1 = WaveSurfer.create({
        container: '#waveform1',
        waveColor: 'blue',
        progressColor: 'purple',
        scrollParent: true,
        dragToSeek: true,
        plugins: [
            Timeline.create(),
            Hover.create(),
            Zoom.create({ scale: 1, scrollParent: true }),
            audio1Regions
        ]
    });
    const wavesurfer2 = WaveSurfer.create({
        container: '#waveform2',
        waveColor: 'green',
        progressColor: 'orange',
        scrollParent: true,
        dragToSeek: true,
        plugins: [
            Timeline.create(),
            Hover.create(),
            Zoom.create({ scale: 1, scrollParent: true }),
            audio2Regions
        ]
    });

    // ... rest of the code
```

--------------------------------

### Get Tafsir (Commentary) for Verse

Source: https://context7.com/tarteelai/quranic-universal-library/llms.txt

Retrieve Tafsir commentary for specific verses with support for multiple tafsir resources.

```APIDOC
## GET /api/v1/tafsirs/for_ayah/{verse_key}

### Description
Retrieve Tafsir commentary for specific verses with support for multiple tafsir resources.

### Method
GET

### Endpoint
/api/v1/tafsirs/for_ayah/{verse_key}

### Parameters
#### Path Parameters
- **verse_key** (string) - Required - The verse key in the format 'chapter_number:verse_number' (e.g., '1:1').

#### Query Parameters
- **resource_ids** (string) - Optional - A comma-separated list of resource IDs for desired tafsirs.

### Request Example
```bash
curl -X GET "https://qul.tarteel.ai/api/v1/tafsirs/for_ayah/1:1" \
  -H "Accept: application/json"
```

### Response
#### Success Response (200)
- **tafsirs** (array) - An array of tafsir objects.
  - **id** (integer) - The unique identifier for the tafsir entry.
  - **resource_id** (integer) - The ID of the tafsir resource.
  - **resource_name** (string) - The name of the tafsir resource.
  - **text** (string) - The commentary text for the verse.
  - **verse_key** (string) - The verse key (e.g., '1:1').

#### Response Example
(Example response structure would be similar to the translations endpoint, but with tafsir-specific fields.)
```json
{
  "tafsirs": [
    {
      "id": 12345,
      "resource_id": 1,
      "resource_name": "Tafsir Ibn Kathir",
      "text": "This verse is the opening of the Quran...",
      "verse_key": "1:1"
    }
  ]
}
```
```

--------------------------------

### Run Rails Database Migrations and Seeds

Source: https://github.com/tarteelai/quranic-universal-library/blob/main/README.md

These commands are used to apply database schema changes and populate the `quran_community_tarteel` database with initial data. Run `rails db:migrate` to apply pending migrations and `rails db:seed` to run the seeder file. These are essential steps after setting up the database.

```ruby
rails db:migrate
rails db:migrate
rails db:seed
```

--------------------------------

### Get Translations for Specific Verse

Source: https://context7.com/tarteelai/quranic-universal-library/llms.txt

Fetch translations for a specific verse (ayah) with support for multiple translation resources and language filtering.

```APIDOC
## GET /api/v1/translations/for_ayah/{verse_key}

### Description
Fetch translations for a specific verse (ayah) with support for multiple translation resources and language filtering.

### Method
GET

### Endpoint
/api/v1/translations/for_ayah/{verse_key}

### Parameters
#### Path Parameters
- **verse_key** (string) - Required - The verse key in the format 'chapter_number:verse_number' (e.g., '2:255').

#### Query Parameters
- **resource_ids** (string) - Optional - A comma-separated list of resource IDs for desired translations.
- **language** (string) - Optional - The language code for the desired translations (e.g., 'en').

### Request Example
```bash
curl -X GET "https://qul.tarteel.ai/api/v1/translations/for_ayah/2:255" \
  -H "Accept: application/json" \
  -d "resource_ids=131,20" \
  -d "language=en"
```

### Response
#### Success Response (200)
- **translations** (array) - An array of translation objects.
  - **id** (integer) - The unique identifier for the translation.
  - **resource_id** (integer) - The ID of the translation resource.
  - **resource_name** (string) - The name of the translation resource.
  - **text** (string) - The translated text of the verse.
  - **verse_key** (string) - The verse key (e.g., '2:255').
  - **language_name** (string) - The name of the language.
  - **language_id** (integer) - The ID of the language.

#### Response Example
```json
{
  "translations": [
    {
      "id": 54523,
      "resource_id": 131,
      "resource_name": "Dr. Mustafa Khattab, the Clear Quran",
      "text": "Allah! There is no god ˹worthy of worship˺ except Him, the Ever-Living, All-Sustaining.",
      "verse_key": "2:255",
      "language_name": "english",
      "language_id": 38
    },
    {
      "id": 54524,
      "resource_id": 20,
      "resource_name": "Sahih International",
      "text": "Allah - there is no deity except Him, the Ever-Living, the Sustainer of existence.",
      "verse_key": "2:255",
      "language_name": "english",
      "language_id": 38
    }
  ]
}
```
```

--------------------------------

### Present Verse Data for API with Eager Loading

Source: https://context7.com/tarteelai/quranic-universal-library/llms.txt

Shows how to use a VersePresenter to format verse data for API responses, including eager loading of related associations like words. It details the structure of the JSON response.

```ruby
# In a controller
class Api::V1::VersesController < ApiController
  def index
    @presenter = V1::VersePresenter.new(self)
    @verses = @presenter.verses_for_chapter(params[:chapter_id])

    render json: {
      verses: @verses.map do |verse|
        {
          id: verse.id,
          verse_key: verse.verse_key,
          verse_number: verse.verse_number,
          text_uthmani: verse.text_uthmani,
          text_imlaei: verse.text_imlaei,
          juz_number: verse.juz_number,
          page_number: verse.page_number,
          words: verse.words.map { |w| w.text_uthmani }
        }
      end
    }
  end
end

# Custom verse formatting
verse = Verse.find_by(verse_key: '1:1')
formatted = {
  verse_key: verse.verse_key,
  chapter: verse.chapter.name_simple,
  text: verse.text_uthmani,
  translation: verse.translations.first&.text,
  audio_url: verse.audio_files.first&.url,
  words_count: verse.words_count,
  page: verse.page_number,
  juz: verse.juz_number
}
```

--------------------------------

### Find and Navigate Chapters - Ruby

Source: https://context7.com/tarteelai/quranic-universal-library/llms.txt

Demonstrates how to interact with chapter data in Ruby, including finding specific chapters by number, accessing chapter metadata like names and verse counts, and filtering chapters by revelation place.

```ruby
# Find a specific chapter
chapter = Chapter.find_by(chapter_number: 2) # Al-Baqarah
puts chapter.name_simple # "Al-Baqarah"
puts chapter.name_arabic # "البقرة"
puts chapter.verses_count # 286
puts chapter.revelation_place # "madinah"
puts chapter.revelation_order # 87

# Get all chapters with translations
chapters = Chapter.includes(:translated_names, :verses)
chapters.each do |chapter|
  puts "#{chapter.chapter_number}. #{chapter.name_simple} (#{chapter.verses_count} verses)"
end

# Filter chapters by revelation place
makkah_chapters = Chapter.where(revelation_place: 'makkah')
madinah_chapters = Chapter.where(revelation_place: 'madinah')
```

--------------------------------

### Restore quran_dev Database using Binary Dump

Source: https://github.com/tarteelai/quranic-universal-library/blob/main/README.md

This snippet illustrates how to restore the `quran_dev` database from a binary dump file using `pg_restore`. This method is generally faster and more efficient for larger databases. Make sure the binary dump file is downloaded and `pg_restore` is available.

```bash
pg_restore --host localhost --port 5432 --no-owner --no-privileges --no-tablespaces --no-acl --dbname quran_dev -v "path to binary dump file"
```

--------------------------------

### Search and Query Verses with Complex Filtering (Ruby)

Source: https://context7.com/tarteelai/quranic-universal-library/llms.txt

Demonstrates advanced verse querying, including finding specific verses by key, navigating between adjacent verses, retrieving verses with all related data (words, translations, audio, tafsirs), finding verses by Juz, Page, or Ruku, searching by root words, and identifying verses with missing translations for a given language.

```ruby
# Find a specific verse
verse = Verse.find_by(verse_key: '2:255') # Ayat al-Kursi
puts verse.text_uthmani # Uthmani Arabic script
puts verse.text_uthmani_simple # Simplified Uthmani script
puts verse.text_imlaei # Modern Arabic spelling
puts verse.words_count # Number of words

# Navigate between verses
next_verse = verse.next_ayah
previous_verse = verse.previous_ayah

# Get verse with all related data
verse = Verse
  .includes(:words, :translations, :audio_files, :tafsirs)
  .find_by(verse_key: '1:1')

# Find verses by Juz, Page, or Ruku
juz_1_verses = Verse.where(juz_number: 1)
page_1_verses = Verse.where(page_number: 1)
ruku_verses = Verse.where(ruku_number: 10)

# Search for related verses by root words
verse = Verse.find_by(verse_key: '2:255')
related_verses = verse.find_related_verses_by_roots.limit(10)
related_verses.each do |related|
  puts "#{related.verse_key}: #{related.word_match_count} matching words"
end

# Find verses with missing translations for a language
missing_verses = Verse.verses_with_missing_translations(38) # English
puts "#{missing_verses.count} verses need translation"
```

--------------------------------

### CSS Styling for Drop Zone and Audio Player UI Elements

Source: https://github.com/tarteelai/quranic-universal-library/blob/main/public/compare-audio.html

This CSS code provides styling for various user interface elements of the audio comparison tool. It includes styles for a drag-and-drop zone (`.drop-zone`) with visual feedback for highlighting during drag operations. It also styles the time display (`.time-display`) to be an absolute-positioned overlay, customizes range input sliders (`input[type="range"]`), and applies focus effects to jump input fields (`#jumpTo1`, `#jumpTo2`) and hover effects to jump buttons (`#jumpButton1`, `#jumpButton2`).

```css
.drop-zone {
  border: 2px dashed #007bff;
  padding: 20px;
  margin: 20px;
  cursor: pointer;
  background-color: #e9f5ff;
  border-radius: 10px;
  transition: background-color 0.3s;
}

.drop-zone.highlight {
  background-color: #6cf65c;
  border-color: #327f29;
}

.time-display {
  background: rgba(0, 0, 0, 0.8);
  color: white;
  padding: 4px 8px;
  border-radius: 4px;
  font-family: monospace;
  font-size: 12px;
  position: absolute;
  top: 10px;
  right: 10px;
  z-index: 10;
}

/* Custom range input styling */
input[type="range"] {
  -webkit-appearance: none;
  appearance: none;
  background: transparent;
}

/* Jump to input styling */
#jumpTo1, #jumpTo2 {
  transition: border-color 0.2s ease;
}

#jumpTo1:focus, #jumpTo2:focus {
  outline: none;
  border-color: #3b82f6;
  box-shadow: 0 0 0 3px rgba(59, 130, 246, 0.1);
}

#jumpButton1, #jumpButton2 {
  transition: all 0.2s ease;
}

#jumpButton1:hover, #jumpButton2:hover {
  transform: translateY(-1px);
}

input[type="range"]::-webkit-slider-thumb {
  -webkit-appearance: none;
  appearance: none;
  background: #8b5cf6;
  height: 16px;
  width: 16px;
  border-radius: 50%;
  cursor: pointer;
}

input[type="range"]::-moz-range-track {
  background: #e5e7eb;
  height: 6px;
  border-radius: 3px;
}

input[type="range"]::-moz-range-thumb {
  background: #8b5cf6;
  height: 16px;
  width: 16px;
  border-radius: 50%;
  cursor: pointer;
  border: none;
}
```

--------------------------------

### Run Cypress Tests in Specific Browser (Headless)

Source: https://github.com/tarteelai/quranic-universal-library/blob/main/scripts/cypress-e2e/readme.md

Executes Cypress tests in a specified browser (e.g., Chrome, Edge, Firefox) in headless mode. This command requires Cypress to be installed.

```bash
npx cypress run --browser chrome
```

--------------------------------

### Manage Resource Content Metadata and Counts

Source: https://context7.com/tarteelai/quranic-universal-library/llms.txt

Demonstrates how to retrieve resource metadata, check for specific features like footnotes or segments, and update record counts. It also shows how to export resource data to SQLite and import draft content.

```ruby
# Get resource metadata
resource = ResourceContent.find(131)
puts "Has footnotes: #{resource.has_footnote?}"
puts "Has segments: #{resource.has_segments?}"
puts "Mushaf layout: #{resource.has_mushaf_layout?}"
puts "QuranEnc key: #{resource.quran_enc_key}"

# Update resource record counts
resource.update_records_count
puts "Updated count: #{resource.records_count}"

# Export resource to SQLite
resource = ResourceContent.find(131)
puts "Export filename: #{resource.sqlite_file_name}"

# Import draft content and run hooks
resource.run_draft_import_hooks # After importing draft data
resource.run_after_import_hooks # After importing final data
```

--------------------------------

### Load Audio from URL with Enter Key

Source: https://github.com/tarteelai/quranic-universal-library/blob/main/public/compare-audio.html

Handles loading audio files from user-provided URLs when the Enter key is pressed in specific input fields. It utilizes the `loadAudioFromURL` function and requires `wavesurfer` instances and corresponding statistics IDs.

```javascript
document.getElementById('url1').addEventListener('keypress', (e) => {
  if (e.key === 'Enter') {
    const url = e.target.value.trim();
    if (url) {
      loadAudioFromURL(wavesurfer1, url, 'stats1');
    }
  }
});
document.getElementById('url2').addEventListener('keypress', (e) => {
  if (e.key === 'Enter') {
    const url = e.target.value.trim();
    if (url) {
      loadAudioFromURL(wavesurfer2, url, 'stats2');
    }
  }
});
```

--------------------------------

### Query Translations Efficiently with Pagination

Source: https://context7.com/tarteelai/quranic-universal-library/llms.txt

Illustrates the usage of a TranslationFinder service for querying translations with options for specific verses, ranges of verses, and pagination. It highlights how to filter by locale and resource content ID.

```ruby
# Initialize translation finder
finder = TranslationFinder.new(
  resource_content_id: 131,
  locale: 'en',
  current_page: 1,
  per_page: 20
)

# Get translations for specific verse
translations = finder.for_ayah(
  ayah_key: '2:255',
  language_code: 'en',
  resource_content_ids: [131, 20, 84]
)

translations.each do |trans|
  puts "#{trans.resource_name}: #{trans.text}"
end

# Get translations for range of verses
verse_ids = (1..7).to_a # First 7 verses
translations = finder.for_ayahs(verse_ids)

# With pagination
finder = TranslationFinder.new(
  resource_content_id: 131,
  locale: 'en',
  current_page: 2,
  per_page: 50
)
page_2_translations = finder.for_ayahs((1..100).to_a)
```

--------------------------------

### Get All Available Translations

Source: https://context7.com/tarteelai/quranic-universal-library/llms.txt

Retrieves metadata for all available translation resources in the system. This allows users to see the different Quran translations offered, along with details like language and author.

```APIDOC
## GET /api/v1/resources/translations

### Description
Retrieve metadata for all available translation resources in the system.

### Method
GET

### Endpoint
/api/v1/resources/translations

### Parameters

#### Query Parameters
None

### Request Example
```bash
curl -X GET "https://qul.tarteel.ai/api/v1/resources/translations" \
  -H "Accept: application/json"
```

### Response
#### Success Response (200)
- **translations** (array) - An array of translation resource objects.
  - **id** (integer) - Unique identifier for the translation resource.
  - **name** (string) - The name of the translation.
  - **author_name** (string) - The name of the author or translator.
  - **language_name** (string) - The name of the language this translation is in.
  - **language_id** (integer) - The unique identifier for the language.
  - **slug** (string) - A URL-friendly identifier for the translation.
  - **approved** (boolean) - Indicates if the translation is approved.
  - **records_count** (integer) - The total number of verses/records in this translation.

#### Response Example
```json
{
  "translations": [
    {
      "id": 131,
      "name": "Dr. Mustafa Khattab, the Clear Quran",
      "author_name": "Dr. Mustafa Khattab",
      "language_name": "english",
      "language_id": 38,
      "slug": "clear-quran",
      "approved": true,
      "records_count": 6236
    },
    {
      "id": 20,
      "name": "Sahih International",
      "language_name": "english",
      "language_id": 38,
      "approved": true,
      "records_count": 6236
    }
  ]
}
```
```

--------------------------------

### Manage Audio Recitation Files and Segments (Ruby)

Source: https://context7.com/tarteelai/quranic-universal-library/llms.txt

Provides code to manage audio recitations, including finding a recitation with its associated audio files, retrieving all approved recitations, cloning a recitation, validating segment data quality for a recitation or specific audio files, and updating audio statistics like file counts and total size. This is essential for handling Quranic audio content.

```ruby
# Find a recitation with all audio files
recitation = Audio::Recitation
  .includes(:chapter_audio_files, :reciter, :recitation_style)
  .find(1)

puts "Recitation: #{recitation.name}"
puts "Reciter: #{recitation.reciter.name}"
puts "Format: #{recitation.audio_format}"
puts "Total files: #{recitation.files_count}"
puts "Has segments: #{recitation.segments_count > 0}"

# Get all approved recitations
approved_recitations = Audio::Recitation
  .approved
  .includes(:reciter)
  .order(priority: :asc)

# Clone a recitation
original = Audio::Recitation.find(1)
cloned = original.clone_with_audio_files
puts "Cloned recitation ID: #{cloned.id}"

# Validate segment data quality
recitation = Audio::Recitation.find(1)
issues = recitation.validate_segments_data

if issues.empty?
  puts "No segment issues found"
else
  issues.each do |issue|
    puts "[#{issue[:severity]}] #{issue[:key]}: #{issue[:text]}"
  end
end

# Validate specific audio file segments
audio_file = Audio::ChapterAudioFile.find_by(
  audio_recitation_id: 1,
  chapter_id: 1
)
file_issues = recitation.validate_segments_data(audio_file: audio_file)

# Update audio statistics
recitation.update_audio_stats
puts "Updated files count: #{recitation.files_count}"
puts "Total size: #{recitation.files_size} bytes"
```

--------------------------------

### Create New Feature Branch

Source: https://github.com/tarteelai/quranic-universal-library/blob/main/README.md

This Git command creates a new branch for your feature development and switches to it. Replace `making-qul` with a descriptive name for your branch. Working on a separate branch helps keep your changes organized and isolated.

```bash
git checkout -b making-qul
```

--------------------------------

### Get Verse Translations API Request

Source: https://context7.com/tarteelai/quranic-universal-library/llms.txt

Retrieves translations for a specific Quran verse (ayah). It supports filtering by `resource_ids` and `language`. This is useful for displaying translations from preferred sources in a chosen language.

```bash
curl -X GET "https://qul.tarteel.ai/api/v1/translations/for_ayah/2:255" \
  -H "Accept: application/json" \
  -d "resource_ids=131,20" \
  -d "language=en"
```

--------------------------------

### JavaScript Load Audio from URL with Player

Source: https://github.com/tarteelai/quranic-universal-library/blob/main/public/compare-audio.html

Loads an audio file from a URL and immediately displays an HTML5 audio player. It also sets up event listeners for time updates and metadata loading to keep the player information current. This function prepares the audio for playback and visual analysis, deferring full waveform generation.

```javascript
async function loadAudioFromURL(waveInstance, url, statsId) { try { // Show loading state document.getElementById(statsId).innerHTML = '<p>Loading audio from URL...</p>'; const playerNumber = statsId.replace('stats', ''); // Show HTML5 audio player immediately const audioPlayerId = statsId.replace('stats', 'audioPlayer'); const audioPlayer = document.getElementById(audioPlayerId); if (audioPlayer) { audioPlayer.src = url; audioPlayer.style.display = 'block'; // Show player controls const playerControls = document.getElementById(`player${playerNumber}Controls`); if (playerControls) { playerControls.style.display = 'block'; } // Set up time update listeners audioPlayer.addEventListener('timeupdate', () => updatePlayerTimeDisplay(playerNumber)); audioPlayer.addEventListener('loadedmetadata', () => updatePlayerTimeDisplay(playerNumber)); audioPlayer.addEventListener('durationchange'
```