Adkar - أذكاري 🌿

Your Spiritual Companion for Daily Remembrance
رفيقك الروحاني في رحلة الذكر والتقرب إلى الله

---

🇬🇧 English

📋 Table of Contents

• ✨ Features Overview
• 📸 Screenshots
• 🛠️ Tech Stack
• 🚀 Getting Started
• 🐳 Docker Deployment
• 💻 Standalone Installation
• 📝 Developer Notes

---

✨ Features Overview

📿 Dhikr Categories & Smart Counting

Browse organized categories of Adhkar (Morning, Evening, Prayer, Sleep, etc.). Each Dhikr card includes a smart counter that tracks your progress with visual feedback, automatic saving, and syncing to your profile. Supports both registered users and guests with seamless data merging upon sign-up.

🕌 Mihrab Asma Allah Al-Husna (99 Names of Allah)

An artistic, interactive experience to explore the 99 Names of Allah based on authentic narrations. Each name is presented with its deep meaning in a calm, meditative "Mihrab" interface with smooth animations and a dedicated counter for personal Dhikr.

🌍 World Map of Dhikr

A live interactive map showing remembrance activity around the globe. See which countries are actively engaged in Dhikr, creating a sense of unity and connection with Muslims worldwide.

📊 Leaderboard

A competitive yet spiritually motivating leaderboard that ranks users by their Dhikr activity. Filter by Today, This Week, This Month, or All Time to see who's leading in remembrance.

❤️ Favorites & Collections (Playlists)

• Add to Favorites: Bookmark your most-read Adhkar for quick access.
• Create Collections: Build custom playlists of Dhikr grouped by your personal preferences or spiritual routines.

🏆 Public Challenges

Community-driven global challenges where users collectively work toward a shared Dhikr goal. Join active challenges, track collective progress, and contribute to the Ummah's remembrance goals.

🪴 Premium Orchard (Gamified Profile)

Your profile features a living garden that grows based on your Dhikr activity. The more you remember Allah, the more plants, trees, birds, and natural elements appear in your personal spiritual oasis. Includes a dynamic day/night cycle and animated scenery.

🏅 Achievements & Badges

Earn badges and achievements for milestones like completing your first 100 Adhkar, maintaining a 7-day streak, or contributing to challenges. Achievements are displayed on your profile.

💬 Community Feedback System

• Submit Ideas 💡: Suggest new features or improvements to the app.
• Report Problems ⚠️: Flag bugs or issues you encounter.
• Suggest a Dhikr 📿: Submit new Adhkar for admin review and approval.

All submissions are sent to the admin dashboard and instantly forwarded via Telegram notifications.

🔔 Telegram Bot Integration

Real-time notifications are sent to a Telegram group/channel whenever:

• A new idea or problem report is submitted.
• A new Dhikr is suggested by a user.
• Supports optional Topic ID for organized group discussions.

🔐 Google Login Integration

Secure authentication via Google OAuth (NextAuth.js). Users can sign in with their Google account, and their guest activity is automatically merged into their profile.

🖼️ Dhikr Card Image Generator

Generate beautiful, shareable Dhikr card images that can be downloaded and shared on social media or messaging apps.

📢 Announcements System

Admins can broadcast announcements (info, updates, warnings, celebrations) that appear prominently across the app for all users.

---

🛡️ Admin Control Panel

A comprehensive, multi-tab admin dashboard with the following capabilities:

Tab	Features
📊 Overview	Dashboard stats, live user count (Socket.IO), quick metrics
📝 Submissions	Review, approve, or reject user-submitted Adhkar
📿 Dhikr Manager	Create, edit, delete Adhkar with category assignment and count goals
📂 Categories	Full CRUD for Dhikr categories with icon and color customization
💬 Reports	View and manage user-submitted ideas and problem reports
🏆 Challenges	Create, activate/deactivate, and monitor global community challenges
📈 Analytics	Detailed charts for Dhikr activity, user growth, top categories, and trending Adhkar
👥 Users	Search, paginate, promote/demote roles, and delete user accounts
📢 Announcements	Create, toggle, and manage app-wide announcements
🏅 Achievements	Design and manage achievement badges with custom conditions
🔧 Maintenance	Data reset tools: reset category clicks, Dhikr clicks, user activity, or perform a full master reset (with confirmation dialogs)

---

📸 Screenshots

Home Page – Browse Dhikr Categories

Mihrab Asma Allah Al-Husna

Evening Adhkar with Smart Counters

Shareable Dhikr Card Generator

Admin Control Panel

---

🛠️ Tech Stack

Technology	Purpose
Next.js 16 (App Router)	Full-stack React framework with Server Actions
TypeScript	Type-safe development
Tailwind CSS	Utility-first styling with custom design tokens
PostgreSQL 16	Relational database
Prisma ORM	Database access and schema management
NextAuth.js v5	Authentication (Google OAuth + Credentials)
Framer Motion	Smooth animations and transitions
Socket.IO	Real-time live user count
Telegram Bot API	Instant admin notifications
Docker & Compose	Containerized deployment

---

🚀 Getting Started

Prerequisites

• Node.js 20+
• Docker (recommended) or a local PostgreSQL instance

Environment Setup

1. Copy the example environment file:

   cp .env-example .env

2. Fill in the required values in .env:

   DATABASE_URL=postgresql://adkar:adkar@db:5432/adkar
   NEXTAUTH_URL=http://localhost:3000
   NEXTAUTH_SECRET=your-random-secret-here
   GOOGLE_CLIENT_ID=your-google-client-id
   GOOGLE_CLIENT_SECRET=your-google-client-secret
   TELEGRAM_BOT_TOKEN=your-telegram-bot-token
   TELEGRAM_CHAT_ID=your-telegram-chat-id
   TELEGRAM_TOPIC_ID=optional-topic-id

---

🐳 Docker Deployment

Build & Run

# Build and start all services (app + database)
docker compose up -d --build

# View logs
docker compose logs -f

# Stop
docker compose down

Administrative Commands (Inside Docker)

After the containers are running:

# Seed the database with initial categories and Adhkar
docker exec -it adkar-app-1 npm run db:seed

# Promote a user to Admin role
docker exec -it adkar-app-1 npm run db:promote-admin admin@example.com

Database Management

# Open Prisma Studio to browse data
npx prisma studio

# Push schema changes to database
npx prisma db push

---

💻 Standalone Installation (without Docker)

1. Install PostgreSQL

# macOS (Homebrew)
brew install postgresql@16
brew services start postgresql@16

For other OS, download from postgresql.org.

2. Create the Database

# Quick setup
createdb adkar

# Or with a dedicated user (matches Docker config)
psql -c "CREATE USER adkar WITH PASSWORD 'adkar';"
psql -c "CREATE DATABASE adkar OWNER adkar;"

3. Configure Environment

cp .env-example .env

Set DATABASE_URL in .env:

DATABASE_URL=postgresql://adkar:adkar@localhost:5432/adkar
NEXTAUTH_URL=http://localhost:3000
NEXTAUTH_SECRET=change-me-to-a-random-secret
AUTH_TRUST_HOST=true

4. Install & Run

# Install dependencies
npm install --legacy-peer-deps

# Setup database schema
npm run db:setup

# Seed initial data (optional)
npm run db:seed

# Start development server
npm run dev

The app will be available at http://localhost:3000 🎉

Quick Reference

Step	Command
Install Postgres	brew install postgresql@16 && brew services start postgresql@16
Create DB	createdb adkar
Set .env	DATABASE_URL=postgresql://localhost:5432/adkar
Install deps	npm install --legacy-peer-deps
Push schema	npm run db:setup
Seed (optional)	npm run db:seed
Run	npm run dev

---

📝 Developer Notes

• When adding new libraries, use --legacy-peer-deps if you encounter React 19 peer dependency conflicts.
• The app uses Server Actions (Next.js App Router) for all data mutations — no separate API routes needed.
• All admin actions are protected with role-based access control on the server side.

---

O Allah, make this work purely for Your sake and benefit Islam and Muslims through it. 🤲✨

---

---

🇸🇦 عربي

📋 فهرس المحتويات

• ✨ نظرة عامة على المميزات
• 📸 صور من التطبيق
• 🛠️ التقنيات المستخدمة
• 🚀 التشغيل والبناء
• 🐳 التشغيل عبر Docker
• 💻 التشغيل المستقل بدون Docker
• 📝 ملاحظات للمطورين

---

✨ نظرة عامة على المميزات

📿 أقسام الأذكار والعداد الذكي

تصفح أقسام منظمة من الأذكار (الصباح، المساء، الصلاة، النوم، إلخ). كل بطاقة ذكر تحتوي على عداد ذكي يتتبع تقدمك مع تغذية بصرية وحفظ تلقائي ومزامنة مع ملفك الشخصي. يدعم المستخدمين المسجلين والزوار مع دمج تلقائي للبيانات عند التسجيل.

🕌 محراب أسماء الله الحسنى

تجربة تفاعلية فنية لاستكشاف أسماء الله الحسنى الـ 99 بناءً على الروايات الصحيحة. كل اسم معروض مع معناه العميق في واجهة "محراب" هادئة مع رسوم متحركة سلسة وعداد مخصص للذكر الشخصي.

🌍 خريطة العالم للأذكار

خريطة تفاعلية حية تعرض نشاط الذكر حول العالم. شاهد الدول التي يُذكر فيها الله بنشاط، مما يعطيك شعوراً بالوحدة والتواصل مع المسلمين في كل مكان.

📊 لوحة المتصدرين

لوحة متصدرين تحفيزية تصنف المستخدمين حسب نشاطهم في الذكر. فلتر حسب اليوم، هذا الأسبوع، هذا الشهر، أو الكل لمعرفة من يتصدر في الذكر.

❤️ المفضلة والمجموعات

• إضافة للمفضلة: احفظ أذكارك الأكثر قراءة للوصول السريع.
• إنشاء مجموعات: أنشئ قوائم تشغيل مخصصة من الأذكار حسب تفضيلاتك الشخصية أو روتينك الروحاني.

🏆 التحديات الجماعية

تحديات عالمية مجتمعية يعمل فيها المستخدمون معاً نحو هدف مشترك من الذكر. انضم إلى التحديات النشطة، وتابع التقدم الجماعي، وساهم في أهداف ذكر الأمة.

🪴 البستان الروحاني (الملف الشخصي)

ملفك الشخصي يحتوي على بستان حي ينمو بناءً على نشاطك في الذكر. كلما أكثرت من ذكر الله، ظهرت نباتات وأشجار وطيور وعناصر طبيعية أكثر في واحتك الروحانية الخاصة. يتضمن دورة ليل ونهار ديناميكية ومشاهد متحركة.

🏅 الأوسمة والإنجازات

اكسب أوسمة وإنجازات عند تحقيق إنجازات مثل إكمال أول 100 ذكر، أو الحفاظ على سلسلة 7 أيام، أو المساهمة في التحديات. تُعرض الإنجازات على ملفك الشخصي.

💬 نظام التواصل المجتمعي

• أرسل فكرة 💡: اقترح ميزات أو تحسينات جديدة للتطبيق.
• أبلغ عن مشكلة ⚠️: بلّغ عن أخطاء أو مشاكل تواجهك.
• اقترح ذكراً 📿: أرسل أذكاراً جديدة لمراجعة المسؤول والموافقة عليها.

جميع الإرسالات تصل إلى لوحة تحكم المسؤول و تُرسل فوراً عبر إشعارات تلغرام.

🔔 ربط بوت تلغرام

إشعارات فورية تُرسل إلى مجموعة/قناة تلغرام عند:

• إرسال فكرة أو تقرير مشكلة جديد.
• اقتراح ذكر جديد من مستخدم.
• يدعم معرّف الموضوع الاختياري لتنظيم المناقشات.

🔐 تسجيل الدخول عبر جوجل

مصادقة آمنة عبر Google OAuth (NextAuth.js). يمكن للمستخدمين تسجيل الدخول بحساب جوجل، ويتم دمج نشاطهم كضيوف تلقائياً في ملفهم الشخصي.

🖼️ مولّد صور بطاقات الأذكار

أنشئ صور بطاقات أذكار جميلة وقابلة للمشاركة يمكن تحميلها ومشاركتها على وسائل التواصل الاجتماعي أو تطبيقات المراسلة.

📢 نظام الإعلانات

يمكن للمسؤولين بث إعلانات (معلومات، تحديثات، تنبيهات، احتفالات) تظهر بشكل بارز عبر التطبيق لجميع المستخدمين.

---

🛡️ لوحة تحكم المسؤول

لوحة تحكم شاملة متعددة الأقسام بالإمكانيات التالية:

القسم	المميزات
📊 نظرة عامة	إحصائيات اللوحة، عدد المستخدمين المباشر (Socket.IO)، مقاييس سريعة
📝 الطلبات	مراجعة واعتماد أو رفض الأذكار المرسلة من المستخدمين
📿 إدارة الأذكار	إنشاء وتعديل وحذف الأذكار مع تعيين الأقسام وأهداف العدد
📂 الأقسام	إدارة كاملة لأقسام الأذكار مع تخصيص الأيقونات والألوان
💬 البلاغات	عرض وإدارة الأفكار والمشاكل المرسلة من المستخدمين
🏆 التحديات	إنشاء وتفعيل/تعطيل ومراقبة التحديات المجتمعية العالمية
📈 التحليلات	رسوم بيانية مفصلة لنشاط الأذكار ونمو المستخدمين وأبرز الأقسام والأذكار الرائجة
👥 المستخدمون	بحث وعرض صفحات وترقية/تخفيض الأدوار وحذف حسابات المستخدمين
📢 الإعلانات	إنشاء وتبديل وإدارة الإعلانات على مستوى التطبيق
🏅 الإنجازات	تصميم وإدارة أوسمة الإنجازات بشروط مخصصة
🔧 الصيانة	أدوات تصفير البيانات: تصفير نقرات الأقسام، نقرات الأذكار، نشاط المستخدمين، أو إجراء مسح شامل (مع نوافذ تأكيد)

---

📸 صور من التطبيق

الصفحة الرئيسية – تصفح أقسام الأذكار

محراب أسماء الله الحسنى

أذكار المساء مع العداد الذكي

مولّد بطاقات الأذكار القابلة للمشاركة

لوحة تحكم المسؤول

---

🛠️ التقنيات المستخدمة

التقنية	الاستخدام
Next.js 16 (App Router)	إطار عمل React كامل مع Server Actions
TypeScript	تطوير آمن بالأنواع
Tailwind CSS	تنسيق مرن مع تصميم مخصص
PostgreSQL 16	قاعدة بيانات علائقية
Prisma ORM	الوصول لقاعدة البيانات وإدارة الهيكل
NextAuth.js v5	المصادقة (Google OAuth + Credentials)
Framer Motion	رسوم متحركة سلسة
Socket.IO	عداد المستخدمين المباشر
Telegram Bot API	إشعارات فورية للمسؤول
Docker & Compose	نشر عبر الحاويات

---

🚀 التشغيل والبناء

المتطلبات الأساسية

• Node.js 20+
• Docker (موصى به) أو PostgreSQL محلي

إعداد البيئة

1. قم بنسخ ملف البيئة التجريبي:

   cp .env-example .env

2. املأ القيم المطلوبة في .env:

   DATABASE_URL=postgresql://adkar:adkar@db:5432/adkar
   NEXTAUTH_URL=http://localhost:3000
   NEXTAUTH_SECRET=your-random-secret-here
   GOOGLE_CLIENT_ID=your-google-client-id
   GOOGLE_CLIENT_SECRET=your-google-client-secret
   TELEGRAM_BOT_TOKEN=your-telegram-bot-token
   TELEGRAM_CHAT_ID=your-telegram-chat-id
   TELEGRAM_TOPIC_ID=optional-topic-id

---

🐳 التشغيل عبر Docker

البناء والتشغيل

# بناء وتشغيل جميع الخدمات (التطبيق + قاعدة البيانات)
docker compose up -d --build

# عرض السجلات
docker compose logs -f

# الإيقاف
docker compose down

أوامر الإدارة (داخل Docker)

بعد تشغيل الحاويات:

# تعبئة قاعدة البيانات بالبيانات الأولية (الأقسام والأذكار)
docker exec -it adkar-app-1 npm run db:seed

# ترقية مستخدم إلى مدير
docker exec -it adkar-app-1 npm run db:promote-admin admin@example.com

إدارة قاعدة البيانات

# فتح Prisma Studio لتصفح البيانات
npx prisma studio

# دفع تغييرات الهيكل لقاعدة البيانات
npx prisma db push

---

💻 التشغيل المستقل بدون Docker

1. تثبيت PostgreSQL

# macOS (باستخدام Homebrew)
brew install postgresql@16
brew services start postgresql@16

لأنظمة التشغيل الأخرى، قم بتحميل PostgreSQL من postgresql.org.

2. إنشاء قاعدة البيانات

# إعداد سريع
createdb adkar

# أو بمستخدم مخصص (يطابق إعداد Docker)
psql -c "CREATE USER adkar WITH PASSWORD 'adkar';"
psql -c "CREATE DATABASE adkar OWNER adkar;"

3. إعداد متغيرات البيئة

cp .env-example .env

عدّل DATABASE_URL في ملف .env:

DATABASE_URL=postgresql://adkar:adkar@localhost:5432/adkar
NEXTAUTH_URL=http://localhost:3000
NEXTAUTH_SECRET=change-me-to-a-random-secret
AUTH_TRUST_HOST=true

4. التثبيت والتشغيل

# تثبيت المكتبات
npm install --legacy-peer-deps

# إعداد هيكل قاعدة البيانات
npm run db:setup

# تعبئة البيانات الأولية (اختياري)
npm run db:seed

# تشغيل خادم التطوير
npm run dev

التطبيق سيكون متاحاً على http://localhost:3000 🎉

مرجع سريع

الخطوة	الأمر
تثبيت Postgres	brew install postgresql@16 && brew services start postgresql@16
إنشاء قاعدة البيانات	createdb adkar
إعداد .env	DATABASE_URL=postgresql://localhost:5432/adkar
تثبيت المكتبات	npm install --legacy-peer-deps
دفع الهيكل	npm run db:setup
تعبئة البيانات (اختياري)	npm run db:seed
تشغيل	npm run dev

---

📝 ملاحظات للمطورين

• عند إضافة مكتبات جديدة، استخدم --legacy-peer-deps إذا واجهت تضارباً في إصدارات React 19.
• يستخدم التطبيق Server Actions (Next.js App Router) لجميع عمليات تعديل البيانات — لا حاجة لمسارات API منفصلة.
• جميع إجراءات المسؤول محمية بنظام التحكم بالأدوار على مستوى الخادم.

---

اللهم اجعل هذا العمل خالصاً لوجهك الكريم وانفع به الإسلام والمسلمين. 🤲✨