[QF-4199] study mode

[afifvdin]

Summary

This PR introduces backend support for Study Mode, specifically implementing the Related Verses functionality. It allows verses to be linked together based on specific relationship types (e.g., similar themes, abrogated/abrogating, etc.), enabling richer contextual study of the Quran.

Closes: QF-4199

Key Changes

• New Models:
  • RelatedVerse: Manages the many-to-many relationship between verses with bidirectional validation.
  • RelationType: Defines the types of relationships available.
  • RelationTypeTranslation: Supports internationalization for relation type names.
• API Endpoints:
  • Added GET /api/v4/related_verses/by_key/:verse_key to fetch verses related to a specific verse key.
  • Updated GET /api/v4/verses/by_key/:verse_key to accept ?related_verses=true param.
• Controllers & Presenters:
  • Api::V4::RelatedVersesController: specific controller to handle related verses logic.
  • VersesPresenter: Updated to support related verses serialization.

Usage Examples

1. Fetch related verses only:

GET /api/v4/related_verses/by_key/1:1

Response Snippet:

{
  "related_verses": [
    {
      "id": 10,
      "verse_id": 25,
      "verse_key": "2:25",
      "relation": "Similar Theme",
      "chapter_name": "Al-Baqarah"
    }
  ]
}

2. Fetch a verse with its related verses:

GET /api/v4/verses/by_key/1:1?related_verses=true

Response Snippet:

{
  "verse": {
    "id": 1,
    "verse_key": "1:1",
    ...
    "related_verses": [
      {
        "id": 10,
        "verse_id": 25,
        "verse_key": "2:25",
        "relation": "Similar Theme",
        "chapter_name": "Al-Baqarah"
      }
    ]
  }
}

[Copilot]

Pull request overview

This PR introduces backend support for Study Mode's Related Verses feature, enabling verses to be linked with specific relationship types (e.g., similar themes, abrogated/abrogating). The implementation provides both a dedicated endpoint and an optional parameter on existing verse endpoints to fetch related verses with proper internationalization support.

• New database schema with three tables: relation_types, relation_type_translations, and related_verses with bidirectional relationship constraints
• API endpoints for fetching related verses by verse key, with optional inclusion in existing verse endpoints
• Full internationalization support through RelationType translations with language fallback logic

Reviewed changes

Copilot reviewed 13 out of 13 changed files in this pull request and generated 9 comments.

Show a summary per file

File	Description
db/migrate/20260101000001_create_relation_types_and_translations.rb	Creates relation types and translations tables with unique constraints
db/migrate/20260101000002_create_related_verses.rb	Creates related verses table with bidirectional uniqueness constraint and approval workflow
config/routes/api/v4.rb	Adds new route for fetching related verses by verse key
app/views/api/v4/verses/_verse.json.streamer	Updates verse template to conditionally include related verses
app/views/api/v4/verses/_related_verse.json.streamer	New partial for rendering individual related verse with localized relation name
app/views/api/v4/related_verses/by_key.json.streamer	New view template for dedicated related verses endpoint
app/presenters/verses_presenter.rb	Adds methods to support related verses rendering with memoization
app/models/verse.rb	Adds bidirectional associations to related_verse_records
app/models/relation_type_translation.rb	New model for storing localized relation type names
app/models/relation_type.rb	New model with localization logic and language fallback
app/models/related_verse.rb	New model with bidirectional validation and scopes for querying relationships
app/models/chapter.rb	Adds methods to efficiently load chapters for related verses display
app/controllers/api/v4/related_verses_controller.rb	New controller for handling related verses requests

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[afifvdin]

done added test