Product Requirements Document: Smart Digital Prayer Clock (Jam Shalat Masjid)

1. Executive Summary

Objective: Develop a world-class, offline-first digital signage application for mosques running continuously (24/7) on Android TV Boxes without internet dependency. Key Directives: Avoid the dated, cluttered spreadsheet look of traditional digital clocks. Implement "The Sacred Horizon" design system, focusing on elegance, high visual impact, wide margins, and asymmetrical editorial layouts.

2. Core Architecture & Tech Stack

Target Platform: Android TV Box (Android 13/14, 4GB RAM, 64GB ROM) — 1920x1080 Landscape Display.
Framework: Flutter (Latest Stable).
Architecture Pattern: Clean Architecture / MVVM.
State Management: Riverpod (Recommended for predictable timer-based state transitions).
Local Storage: Isar (High-performance NoSQL for offline caching of monthly APIs and Settings).
Background Management: wakelock_plus package must be implemented to prevent screen sleeping. Timer handling must be memory-leak safe.

3. Design System Strategy: "The Sacred Horizon"

Creative North Star: "The Celestial Anchor" - Calm, reverence, and absolute clarity.
Color Palette:
- Background (The Void): #131313
- Primary (Living Green): #88d982 (Used for current time status and active prayer highlights)
- Secondary (Sacred Gold): #e9c349 (Used for alerts, Jumu'ah highlights, running text)
Typography:
- Plus Jakarta Sans: Display (3.5rem - 12rem), used for the massive clock, prayer titles. Bold and commanding. Letter-spacing tighter (-0.02em).
- Manrope: Used for functional elements (Sub-timers, info panels, marquee). Clean and readable from 2-3 meters.
Surfaces & Depth (The "No-Line" Rule):
- Strictly NO 1px solid borders between content. Separation is created using tonal layering (e.g. surface_container_low #1c1b1b over #131313 background).
- Use frosted glass effects (backdrop-filter) for floating overlays. Give active items ambient glows instead of hard drop shadows.

4. App State Machine & UI Experiences

The application transitions through a cyclical logic based on DateTime.now().

State 1: NORMAL / ROTATION

Automatically rotates between Main View and Slideshow based on Admin configurations using smooth AnimatedSwitcher.

Main Screen: Asymmetrical layout. High-contrast massive clock in the center/center-left. Hijri & Gregorian dates. Bottom Area: 5/6 prayer cards spanning horizontally. The active/upcoming prayer is elevated using primary_container color. Bottom Edge: Continuous marquee text.
Slideshow Screen: Cinematic full-screen graphic behind a subtle gradient overlay. A floating "Glass" widget anchors to the top-right showing current time and upcoming prayer countdown. Central focus is on the poster/quote text.

State 2: MENUJU ADZAN

Triggered ~X minutes before the exact prayer time (configurable per prayer).
Forced lock to Main Screen (cancels slideshow rotations). Focus shifted to the active countdown. Pulsing UI indicators.

State 3: ADZAN (Time Reached)

Full-screen alert takeover. Glowing Secondary texts: "WAKTU ADZAN [NAMA SHALAT]". Short audio chime.

State 4: MENUJU IQOMAH

Massive, dominant countdown timer taking over the screen center. "PERSIAPAN SHALAT. Luruskan dan rapatkan shaf".
Jumu'ah Override: On Fridays, Dzuhur is replaced with "JUMAT". During the Iqomah countdown phase, the screen transforms into a "Friday Khutbah Information" panel—displaying Imam and Khatib names with an overarching countdown to the Khutbah itself.

State 5: SHALAT / BLACK SCREEN

Post-iqomah. Screen turns to absolute minimal Black (#000000).
Only low-opacity (10-15%) texts remain: "Shalat Sedang Berlangsung" and "Mohon Nonaktifkan Alat Komunikasi".

State 6: KEMBALI NORMAL

System resets to STATE 1 after the configured blank screen duration ends.

5. Offline-First API & Admin Configuration

The App runs 99% offline. Admin dashboard is accessed securely (e.g., hidden D-pad combo).

TV-Optimized Admin UX: Driven purely by D-Pad logic. Focus management is critical (High contrast borders & states for selected inputs). Avoid heavy typing by utilizing sliders, presets, and large selection buttons.
Admin Features (Bento Grid Layout):
1. Identity Settings: Mosque Name, Address.
2. Sync Data: The only feature that requires internet (via mobile tethering). Button pulls 1 full month of data from public prayer API based on City ID.
3. Timing & Durations:
  - Pre-Adzan Lead (minutes per prayer).
  - Iqomah Duration (minutes per prayer).
  - Blank Screen Duration (minutes, separate for normal days and Friday).
4. Appearance: Marquee text configuration, Khatib / Imam input fields for the week.

6. Implementation Roadmap

Phase 1: Foundation Setup: Initialize Flutter project, Riverpod, Isar database, and wakelock_plus. Define configuration models.
Phase 2: Data layer & State Machine: API fetching, offline database seed logic. Build the central Timer loop dictating the State Machine.
Phase 3: Design System Tokens: Translate "The Sacred Horizon" stitch designs into global Flutter themes, custom text styles, and core widgets.
Phase 4: TV UI Development:
- Build all 5 UI states (Normal/Slideshow, Adzan Alert, Iqomah Countdown, Khutbah Override, Black Screen).
Phase 5: TV Admin Dashboard: Implement the D-Pad optimized configuration interface ensuring state saves correctly to Isar.
Phase 6: Final Polish: Focus transition animations, memory leak testing (crucial for 24/7 runtimes), and Android APK generation.

5.8 KiB Raw Blame History