Skip to content

Rayhan-Rakib1/Quran-web-application-server

BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

3 Commits
prisma/schema
prisma/schema
 
 
src
src
 
 
.gitignore
.gitignore
 
 
README.md
README.md
 
 
package.json
package.json
 
 
pnpm-lock.yaml
pnpm-lock.yaml
 
 
tsconfig.json
tsconfig.json
 
 
vercel.json
vercel.json
 
 

Repository files navigation

📖 Quran Web Application — Backend API

Bun Hono TypeScript Node.js License

A blazing-fast REST API for the Quran Web Application built with Hono + Bun + TypeScript.

Live Demo · Frontend Repo · Report Bug · Request Feature

📋 Table of Contents

🌟 Overview

This is the backend service for the Quran Web Application — a full-stack platform to read, listen to, and search the Holy Quran. The API provides all 114 Surahs with Arabic text, English translations (Saheeh International), verse-level audio URLs, full-text search, and reciter management.

Built with Hono (ultra-fast web framework) running on Bun (fast JavaScript runtime), fully typed with TypeScript.

🛠️ Tech Stack

Layer Technology Version
Runtime Bun 1.0+
Framework Hono 4.0+
Language TypeScript 5.0+
Database Quran JSON (local) —
Audio CDN Islamic Network CDN —

✨ Features

  • ⚡ Ultra-fast responses powered by Bun runtime
  • 🕌 All 114 Surahs with complete Arabic text and English translation
  • 🔊 Audio URL generation for every Ayah with multiple reciters
  • 🔍 Full-text search across Arabic and English translations with pagination
  • 📖 Verse-level data — Surah number, Juz, Page, revelation type
  • 🛡️ Type-safe — 100% TypeScript with strict mode
  • 🌐 CORS-ready for frontend integration
  • 📝 Request logging for debugging
  • ❗ Structured error handling with meaningful messages

📁 Project Structure

backend/
├── src/
│   ├── index.ts                 # Entry point — server setup & routes
│   ├── routes/
│   │   ├── surah.ts             # Surah list & detail endpoints
│   │   ├── ayah.ts              # Single ayah endpoint
│   │   ├── search.ts            # Full-text search endpoint
│   │   ├── audio.ts             # Audio URL endpoints
│   │   └── reciter.ts           # Reciter list & detail endpoints
│   ├── middleware/
│   │   ├── cors.ts              # CORS configuration
│   │   ├── logger.ts            # Request logger
│   │   └── errorHandler.ts      # Global error handler
│   ├── data/
│   │   └── quran.json           # Quran data (Arabic + Translation)
│   ├── types/
│   │   └── index.ts             # Shared TypeScript interfaces
│   └── utils/
│       ├── quranHelper.ts       # Data access helper functions
│       └── audioHelper.ts       # Audio URL builder & reciter list
├── package.json
├── tsconfig.json
├── bunfig.toml
└── README.md

🚀 Getting Started

Prerequisites

Make sure you have the following installed:

# Check Bun version
bun --version

# Install Bun if not installed
curl -fsSL https://bun.sh/install | bash

Installation

# 1. Clone the repository
git clone https://github.com/yourusername/quran-backend.git

# 2. Navigate to the backend directory
cd quran-backend

# 3. Install dependencies
bun install

Environment Variables

Create a .env file in the root of the backend directory:

cp .env.example .env

Then fill in the values:

# Server
PORT=3001
NODE_ENV=development

# CORS — comma-separated allowed origins
ALLOWED_ORIGINS=http://localhost:3000,https://your-frontend.vercel.app

# Audio CDN Base URL
AUDIO_CDN_BASE=https://cdn.islamic.network/quran/audio/128

⚠️ Never commit your .env file. It is already in .gitignore.

Running the Server

# Development (with hot reload)
bun run dev

# Production
bun run start

The server will start at:

🚀 Server running at http://localhost:3001

📡 API Reference

Base URL

Development:  http://localhost:3001
Production:   https://your-api.vercel.app

1. Surah Endpoints

Get All Surahs

GET /api/surah

Returns a list of all 114 Surahs with metadata (no ayahs).

Parameter Type Required Description
— — — No parameters

Get Surah by ID

GET /api/surah/:id

Returns metadata for a single Surah.

Parameter Type Required Description
id number ✅ Surah number (1–114)

Get All Ayahs of a Surah

GET /api/surah/:id/ayahs

Returns all verses of a Surah with Arabic text, English translation, and audio URL.

Parameter Type Required Description
id number ✅ Surah number (1–114)
reciter string ❌ Reciter ID (default: alafasy)

2. Ayah Endpoints

Get Single Ayah

GET /api/ayah/:surahId/:ayahId

Returns a specific verse from a specific Surah.

Parameter Type Required Description
surahId number ✅ Surah number (1–114)
ayahId number ✅ Verse number within the Surah
reciter string ❌ Reciter ID (default: alafasy)

3. Search Endpoints

Search Ayahs

GET /api/search?q={keyword}&page={page}&limit={limit}

Full-text search across Arabic and English translation of all Ayahs.

Parameter Type Required Default Description
q string ✅ — Search keyword (Arabic or English)
page number ❌ 1 Page number for pagination
limit number ❌ 10 Results per page (max: 50)

4. Audio Endpoints

Get Audio URL for Single Ayah

GET /api/audio/:ayahNumber

Returns the CDN audio URL for a specific Ayah (global Ayah number, 1–6236).

Parameter Type Required Description
ayahNumber number ✅ Global Ayah number (1–6236)
reciter string ❌ Reciter ID (default: alafasy)

Get All Audio URLs for a Surah

GET /api/audio/surah/:id

Returns an array of audio URLs for every verse in a Surah.

Parameter Type Required Description
id number ✅ Surah number (1–114)
reciter string ❌ Reciter ID (default: alafasy)

5. Reciter Endpoints

Get All Reciters

GET /api/reciters

Returns a list of all available Quran reciters.

Get Reciter by ID

GET /api/reciters/:id

Returns details of a specific reciter.

Parameter Type Required Description
id string ✅ Reciter ID (e.g. alafasy)

Available Reciter IDs:

ID Name
alafasy Mishary Al-Afasy
sudais Abdur Rahman Al-Sudais
husary Mahmoud Khalil Al-Husary
minshawi Mohamed Siddiq Al-Minshawi
ghamdi Saad Al-Ghamdi

💬 Request & Response Examples

✅ Get All Surahs

Request:

curl http://localhost:3001/api/surah

Response:

{
  "success": true,
  "total": 114,
  "data": [
    {
      "number": 1,
      "name": "سورة الفاتحة",
      "englishName": "Al-Faatiha",
      "englishNameTranslation": "The Opening",
      "numberOfAyahs": 7,
      "revelationType": "Meccan"
    },
    {
      "number": 2,
      "name": "سورة البقرة",
      "englishName": "Al-Baqara",
      "englishNameTranslation": "The Cow",
      "numberOfAyahs": 286,
      "revelationType": "Medinan"
    }
  ]
}

✅ Get Surah Ayahs

Request:

curl http://localhost:3001/api/surah/1/ayahs?reciter=alafasy

Response:

{
  "success": true,
  "surah": {
    "number": 1,
    "name": "سورة الفاتحة",
    "englishName": "Al-Faatiha",
    "englishNameTranslation": "The Opening",
    "revelationType": "Meccan"
  },
  "total": 7,
  "data": [
    {
      "number": 1,
      "numberInSurah": 1,
      "arabic": "بِسْمِ ٱللَّهِ ٱلرَّحْمَٰنِ ٱلرَّحِيمِ",
      "translation": "In the name of Allah, the Entirely Merciful, the Especially Merciful.",
      "juz": 1,
      "page": 1,
      "audioUrl": "https://cdn.islamic.network/quran/audio/128/ar.alafasy/1.mp3"
    }
  ]
}

✅ Search Ayahs

Request:

curl "http://localhost:3001/api/search?q=mercy&page=1&limit=5"

Response:

{
  "success": true,
  "query": "mercy",
  "total": 45,
  "page": 1,
  "limit": 5,
  "totalPages": 9,
  "data": [
    {
      "surahNumber": 1,
      "surahName": "سورة الفاتحة",
      "surahEnglishName": "Al-Faatiha",
      "ayahNumber": 1,
      "numberInSurah": 1,
      "arabic": "بِسْمِ ٱللَّهِ ٱلرَّحْمَٰنِ ٱلرَّحِيمِ",
      "translation": "In the name of Allah, the Entirely Merciful..."
    }
  ]
}

❗ Error Handling

All errors follow a consistent structure:

{
  "success": false,
  "message": "Human-readable error description"
}
HTTP Code Meaning
200 Success
400 Bad Request — invalid parameters
404 Not Found — resource does not exist
500 Internal Server Error

Example error response:

{
  "success": false,
  "message": "সূরা নম্বর ১ থেকে ১১৪ এর মধ্যে হতে হবে"
}

🚢 Deployment

Deploy to Vercel

# Install Vercel CLI
npm i -g vercel

# Deploy
vercel --prod

Add a vercel.json in the root:

{
  "builds": [
    {
      "src": "src/index.ts",
      "use": "@vercel/node"
    }
  ],
  "routes": [
    {
      "src": "/(.*)",
      "dest": "src/index.ts"
    }
  ]
}

Deploy to Railway / Render

# Build command
bun install

# Start command
bun run start

Set the environment variables in the platform dashboard matching your .env file.

🤝 Contributing

Contributions are welcome! Please follow these steps:

# 1. Fork the repository

# 2. Create a feature branch
git checkout -b feature/your-feature-name

# 3. Commit your changes (use conventional commits)
git commit -m "feat: add new reciter support"

# 4. Push to your fork
git push origin feature/your-feature-name

# 5. Open a Pull Request

Commit Message Convention:

Prefix Usage
feat: New feature
fix: Bug fix
docs: Documentation update
refactor: Code refactor
chore: Dependency updates

📜 License

This project is licensed under the MIT License — see the LICENSE file for details.

🙏 Acknowledgements

Made with ❤️ for the Muslim Ummah

⭐ Star this repo if you found it useful!

About

quran-web-application-server-sage.vercel.app

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages