Imported from SchumacherFarad/cepte-islam (AGENTS.md). Install upstream with npx skills add SchumacherFarad/cepte-islam. Copyright stays with the author.

Cepte İslam - Project Specification

📱 Project Overview

• App Name: Cepte İslam (Islam in Your Pocket)
• Type: Cross-platform Islamic Mobile Application
• Core Features: Prayer Times, Quran (Read/Audio), Dhikr/Adhkar, Qibla Direction
• Target Audience: Turkish Muslims (primary), English speakers (secondary)
• Platforms: Android, Web, Desktop (iOS later)
• Timeline: 1-3 months MVP

🛠 Tech Stack

🌐 APIs to Use

1. Prayer Times

• Primary: AlAdhan.com (https://aladhan.com/prayer-times-api)
• Documentation: https://aladhan.com/prayer-times-api
• Endpoints:
  • GET /timings/{date}?latitude={lat}&longitude={lng}&method={method}
  • Methods: 4 (Umm al-Qura), 5 (Egyptian), 7 (Muslim World League)
• No API key required

2. Quran

• Primary: AlQuran.cloud (https://api.alquran.cloud)
• Turkish Translation: Diyanet (tr.diyanet)
• Audio: Available via API
• Endpoints:
  • GET /surah - All surahs
  • GET /surah/{id} - Specific surah
  • GET /surah/{id}/{verse} - Specific verse
  • GET /surah/{id}/tr.diyanet - Turkish translation
• Audio: GET /surah/{reciter}/{surah} - Audio recitations

3. Qibla Direction

• Primary: Calculated locally using formula or AlAdhan
• Alternative: UmmahAPI (https://ummahapi.com/api/qibla)

4. Dhikr/Adhkar

• Source: Local database (Hisnul Muslim data)
• Data: JSON files in assets/data/

🎨 Design Specification

Design Reference

• Primary Reference: Diyanet Quran (https://kuran.diyanet.gov.tr/mushaf_v2)
• The Quran reader (Mushaf and Surah detail) follows the clean, modern Diyanet style

Color Palette

Typography

• Font Family: Poppins (Google Fonts)
• Headings: Poppins SemiBold/Bold
• Body: Poppins Regular
• Quran Arabic: Amiri or Uthmani Font
• Sizes:
  • H1: 28sp
  • H2: 24sp
  • H3: 20sp
  • Body: 16sp
  • Caption: 12sp

Icons

• Style: Material Icons + Custom Islamic Icons (mixed)
• Library: flutter_svg for custom icons

UI Style

• Design: Minimalist with subtle Islamic geometric patterns
• Animations: Minimal - smooth transitions but not distracting
• Dark Mode: Manual toggle + System follow option
• Quran Reader: Clean, modern design similar to Diyanet website:
  • Reading mode selector (Kur'an + Meal, Kur'an, Meal)
  • Quick navigation (Cüz, Sure selectors)
  • Page slider with page number display
  • Clean verse display with Arabic numerals for verse numbers
  • Simple translation display below Arabic text

📂 Project Structure

cepte_islam/
├── lib/
│   ├── main.dart
│   ├── app.dart
│   ├── core/
│   │   ├── constants/
│   │   │   ├── app_colors.dart
│   │   │   ├── app_strings.dart
│   │   │   └── api_constants.dart
│   │   ├── theme/
│   │   │   ├── app_theme.dart
│   │   │   └── app_text_styles.dart
│   │   ├── utils/
│   │   │   ├── location_helper.dart
│   │   │   └── date_utils.dart
│   │   └── widgets/
│   │       └── common_widgets.dart
│   ├── data/
│   │   ├── datasources/
│   │   │   ├── remote/
│   │   │   │   ├── prayer_times_api.dart
│   │   │   │   └── quran_api.dart
│   │   │   └── local/
│   │   │       ├── dhikr_local_datasource.dart
│   │   │       └── database_helper.dart
│   │   ├── models/
│   │   │   ├── prayer_times_model.dart
│   │   │   ├── surah_model.dart
│   │   │   └── dhikr_model.dart
│   │   └── repositories/
│   │       ├── prayer_times_repository.dart
│   │       ├── quran_repository.dart
│   │       └── dhikr_repository.dart
│   ├── features/
│   │   ├── prayer_times/
│   │   │   ├── presentation/
│   │   │   │   ├── pages/
│   │   │   │   │   └── prayer_times_page.dart
│   │   │   │   └── widgets/
│   │   │   │       └── prayer_card.dart
│   │   │   └── providers/
│   │   │       └── prayer_times_provider.dart
│   │   ├── quran/
│   │   │   ├── presentation/
│   │   │   │   ├── pages/
│   │   │   │   │   ├── quran_home_page.dart
│   │   │   │   │   └── surah_detail_page.dart
│   │   │   │   └── widgets/
│   │   │   │       └── surah_tile.dart
│   │   │   └── providers/
│   │   │       └── quran_provider.dart
│   │   ├── dhikr/
│   │   │   ├── presentation/
│   │   │   │   ├── pages/
│   │   │   │   │   └── dhikr_page.dart
│   │   │   │   └── widgets/
│   │   │   │       └── dhikr_card.dart
│   │   │   └── providers/
│   │   │       └── dhikr_provider.dart
│   │   └── qibla/
│   │       ├── presentation/
│   │       │   └── pages/
│   │       │       └── qibla_page.dart
│   │       └── providers/
│   │           └── qibla_provider.dart
│   └── l10n/
│       ├── app_tr.arb
│       └── app_en.arb
├── assets/
│   ├── data/
│   │   └── dhikr.json
│   ├── fonts/
│   │   └── amiri/
│   └── icons/
└── pubspec.yaml

✅ Features Priority

Phase 1 - MVP (v1.0)

1. Prayer Times

   • Location-based prayer times
   • Manual city selection
   • Prayer time notifications
   • Daily prayer schedule view

2. Quran

   • Surah list
   • Verse reading with Turkish translation
   • Audio playback (streaming)
   • Last read position (local storage)

3. Dhikr/Adhkar

   • Morning and evening adhkar
   • Category-based listing
   • Mark as read

4. Qibla Direction

   • Compass-based direction
   • Degree display

Phase 2 (v1.1+)

• Hadith collections (Turkish)
• Tasbih (basic)
• iOS support

📋 Development Phases

Phase 1: Setup (Week 1)

• Flutter project init
• Theme and routing setup
• Dependencies (dio, riverpod, sqflite, etc.)
• Clean architecture folder structure
• API service classes

Phase 2: Prayer Times (Week 2)

• Location permission handling
• AlAdhan API integration
• Prayer times UI
• City selector
• Notification system

Phase 3: Quran (Week 3-4)

• AlQuran.cloud API integration
• Surah listing
• Verse detail page
• Audio player integration
• Last read tracking (local DB)

Phase 4: Dhikr & Qibla (Week 5)

• Local dhikr database
• Dhikr UI
• Qibla compass implementation

Phase 5: Polish (Week 6)

• Dark mode
• Turkish/English localization
• Offline caching
• Performance optimization

Phase 6: Release (Week 7-12)

• AdMob integration
• Play Store build
• Web build
• Desktop build

📦 Required Packages (pubspec.yaml)

dependencies:
  flutter:
    sdk: flutter
  
  # State Management
  flutter_riverpod: ^2.4.9
  riverpod_annotation: ^2.3.3
  
  # HTTP
  dio: ^5.4.0
  
  # Local Storage
  sqflite: ^2.3.2
  shared_preferences: ^2.2.2
  path: ^1.8.3
  
  # Location
  geolocator: ^11.0.0
  geocoding: ^2.1.1
  
  # UI
  flutter_svg: ^2.0.9
  google_fonts: ^6.1.0
  flutter_compass: ^0.7.0
  
  # Audio
  just_audio: ^0.9.36
  
  # Notifications
  flutter_local_notifications: ^16.3.2
  timezone: ^0.9.2
  
  # Utils
  intl: ^0.19.0
  connectivity_plus: ^5.0.2

dev_dependencies:
  flutter_test:
    sdk: flutter
  flutter_lints: ^3.0.1
  build_runner: ^2.4.8
  riverpod_generator: ^2.3.9

🔧 Environment Setup

Linux (Arch)

# Install Flutter
sudo pacman -S git curl unzip xz-utils zip
cd ~
git clone https://github.com/flutter/flutter.git -b stable --depth 1
echo 'export PATH="$PATH:$HOME/flutter/bin"' >> ~/.zshrc
source ~/.zshrc

# Install Android SDK
sudo pacman -S android-sdk android-sdk-platform-tools android-sdk-build-tools
# OR use AUR
yay -S flutter

# Verify
flutter --version
flutter doctor

🚀 Running the Project

# Get dependencies
flutter pub get

# Run on connected device
flutter run

# Build APK
flutter build apk --debug
flutter build apk --release

# Build Web
flutter build web

# Build Desktop
flutter build linux

📝 Next Steps (Immediate Actions)

1. Install Flutter (see Environment Setup above)
2. Create Flutter project: flutter create cepte_islam
3. Set up pubspec.yaml with dependencies
4. Create folder structure
5. Implement core theme and constants
6. Start with Prayer Times feature

📚 API Documentation Links

• AlAdhan Prayer Times: https://aladhan.com/prayer-times-api
• AlQuran Cloud: https://api.alquran.cloud
• Flutter Docs: https://docs.flutter.dev

Last Updated: March 2026 Prepared by: OpenCode AI Assistant