jamshalat-masjid-screen/README.md

JamShalat Masjid Screen

Smart digital prayer clock and mosque signage app built with Flutter for Android TV boxes and landscape displays.

Purpose

This app is meant to run continuously inside a mosque as a full-screen prayer information display. It combines:

• live clock and daily prayer schedule
• pre-adzan and adzan alert states
• iqomah countdown flow
• Friday (Jumat) special screens
• black screen during prayer
• slideshow and branded background support
• local admin panel for changing mosque identity, timing, and appearance settings

The product direction is documented in PRD.md.

Current Stack

• Flutter
• Riverpod for app state
• Hive for local persistence
• http for remote APIs
• wakelock_plus for always-on screen behavior
• audioplayers for adzan and iqomah sounds

Current Architecture

The current implementation is a pragmatic Flutter app centered around:

• lib/main.dart: app bootstrap, Hive initialization, fullscreen setup
• lib/providers.dart: clock stream, settings state, screen-state machine, slideshow rotation
• lib/data/local/models.dart: Hive models and adapters
• lib/data/services/: sync, prayer API, background API, sound service
• lib/features/home/: public display screens
• lib/features/admin/: settings/admin panel

This is not yet a strict Clean Architecture / MVVM implementation from the PRD. It is a working product foundation optimized for iteration speed.

Implemented Screens

• Main screen
• Slideshow screen
• Adzan alert screen
• Iqomah countdown screen
• Friday preparation screen
• Friday khutbah screen
• Black screen during prayer
• Admin settings screen

Data Sources

• Prayer times: MyQuran sholat API
• Background images: Unsplash API

The app is designed to behave offline-first after schedule data has been synced and stored locally.

Assets

Included assets currently used by the app:

• fonts: Plus Jakarta Sans, Manrope
• sounds: beep.mp3, 3-detik-countdown.mp3
• images: app icon and user-configured local slideshow/background images

Local Development

Requirements

• Flutter SDK installed and available in PATH
• Android toolchain if building APKs

Run

flutter pub get
flutter run

Analyze

flutter analyze

Test

flutter test

Build Release APK

./scripts/build_release_apk.sh

Artifacts will be written to dist/android/:

• versioned APK: jamshalat-masjid-screen-v<version>-build<code>.apk
• latest APK copy: jamshalat-masjid-screen-latest.apk
• checksum file: *.sha256
• update JSON template: latest.json.example

Android Production Signing

Release APKs now require real signing config. Before building:

1. Copy android/key.properties.example to android/key.properties
2. Fill in your real keystore values
3. Put the keystore file under android/keystore/ or update storeFile accordingly

Example:

storePassword=YOUR_STORE_PASSWORD
keyPassword=YOUR_KEY_PASSWORD
keyAlias=upload
storeFile=keystore/upload-keystore.jks

Notes:

• android/key.properties
• android/keystore/
• *.jks

are ignored by Git and must stay private.

The release build now fails fast if signing is not configured, so you cannot accidentally produce another debug-signed production APK.

Current Stabilization Status

The app is in a workable development state, but not yet fully stabilized.

Known issues at the time of writing:

• test/widget_test.dart is broken placeholder boilerplate and currently fails flutter test
• Android manifest does not yet declare INTERNET, which will block API-dependent features on device
• there are multiple deprecated withOpacity usages reported by flutter analyze
• some placeholders are still hardcoded, including Hijri date text in Friday-related screens
• README and repo hygiene were incomplete and are being normalized

Immediate Priorities

1. Fix test baseline so flutter test becomes useful again.
2. Add Android INTERNET permission.
3. Remove broken placeholders and obvious UI/data defects.
4. Stabilize schedule sync and runtime state transitions.
5. Continue feature work from the PRD after the baseline is reliable.

Notes About Git

This workspace currently does not contain a local .git directory even though a remote repository exists:

• https://git.backoffice.biz.id/dwindown/jamshalat-masjid-screen.git

If needed, the local folder can be attached to that remote in a follow-up step.