Lightweight and modern styling approach
--- **Cons** -Learning curve for Tailwind if new to utility-first CSS
--- **Alternative Approaches** - Material-UI (MUI) - Ant Design - Chakra UI - Custom components from scratch #### **1. Mobile UI Approach:** **What solution did I choose?** I chose **not to use any mobile component library**. I use **NativeWind** for styling, along with **Figma MCP**, **Figma Make**, and **Figma Dev Tools**. **Why did I choose this solution?** - The app uses a **fully custom UI designed in Figma**, so prebuilt component libraries are not a good fit - NativeWind works like **Tailwind CSS**, making styling simple and consistent - Utility-based styling works well with **LLMs** for generating and adjusting UI code - Figma MCP and Figma Make help convert design decisions into implementation guidance - Figma Dev Tools allow developers and LLMs to inspect spacing, colors, and layout accurately - NativeWind allows theme-based styling (colors, spacing, dark mode) **Cons** -No ready-made components out of the box
-More manual work during initial development
### f. Supporting Libraries & Tools #### Zustand (State Management) **What solution did I choose?** I chose **Zustand** for global state management. **Why did I choose this solution?** - Simple and lightweight API - Minimal boilerplate compared to other state managers - Works well with React and React Native **Alternative Approaches** - Redux Toolkit - Jotai --- #### React Query (Server State & Data Fetching) **What solution did I choose?** I chose **React Query** for data fetching and server state management. **Why did I choose this solution?** - Handles caching, loading, and error states automatically - provide all request states by default ( `isPending, isError, isFetching , isLoadin,isFetching`) - .Reduces manual API state handling - Works well with REST APIs - Improves app performance - Simplifies async data logic **Alternative Approaches** - SWR - Manual data fetching - Redux Toolkit Query --- #### Axios (HTTP Client) **What solution did I choose?** I chose **Axios** for making HTTP requests. **Why did I choose this solution?** - Simple API - Supports request and response interceptors. (eg for handling access tokens and refresh tokens) - Works well with authentication and error handling **Alternative Approaches** - Native fetch API - Ky --- #### Postman (API Testing) **What solution did I choose?** I chose **Postman** for API testing and debugging. **Why did I choose this solution?** - Easy to test APIs during development - Easy to share requests and collections with the team - Supports environments and collections - Postman is simpler and more familiar to the team **Alternative Approaches** - Swagger **Why Postman Over Swagger:** - **Collaboration & Manual Collection Import** - Easy to share requests and collections with the team - **Environment Variables** - Supports dev, staging, prod easily for testing - **Ease of Use** - Postman is simpler and more familiar to the team - Swagger is mainly for **documentation and simple API testing**, while Postman is primarily for **API testing and debugging** --- #### next-intl (Internationalization) **What solution did I choose?** I chose **next-intl** for internationalization in the web app. **Why did I choose this solution?** - Designed specifically for Next.js - Supports server and client components - Easy locale-based routing - Already using it in Irchademy **Alternative Approaches** - react-i18next --- #### React Hook Form + Zod (Forms & Validation) **What solution did I choose?** I chose **React Hook Form** with **Zod** for form handling and validation. **Why did I choose this solution?** - Clean validation logic - Works well with shadcn (shdacn support it by default) - Good developer experience - Schema-based validation - Strong TypeScript support **Alternative Approaches** - Formik + Yup - Native form handling #### Moment.js (Date & Time Handling) **What solution did I choose?** I chose **Moment.js** for handling and formatting dates and times. **Why did I choose this solution?** - Simplifies date formatting and manipulation - Easy to use for common date operations - Widely known and documented - Handles time zones and localization - Large ecosystem and examples **Alternative Approaches** - Day.js - date-fns ## 2. Application Architecture & Project Structure ### a. Backend Folder Structure (NestJS) **What solution did I choose?** ```bash saheb-backend/ ├── src/ │ ├── common/ │ │ ├── decorators/ │ │ │ ├── metadata/ │ │ │ │ ├── public.decorator.ts # @Public decorator for public routes │ │ │ │ └── roles.decorator.ts # @Roles decorator for role-based access │ │ │ └── requests/ │ │ │ └── current-user.decorator.ts # @CurrentUser decorator to extract user from request │ │ ├── entities/ │ │ │ └── base.entity.ts # Base entity with common fields │ │ └── guards/ │ │ └── roles.guard.ts # Role-based authorization guard │ ├── configs/ │ │ ├── database.config.ts # Database configuration │ │ ├── jwt.config.ts # JWT configuration │ │ ├── pino-logger.config.ts # Logger configuration │ │ └── throtttle.config.ts # Rate limiting configuration │ ├── modules/ │ │ ├── auth/ │ │ │ ├── dto/ │ │ │ │ └── auth.dto.ts # Auth DTOs (login, register, etc.) │ │ │ ├── guards/ │ │ │ │ └── access-token.guard.ts # JWT access token guard │ │ │ ├── strategies/ │ │ │ │ └── access-token.strategy.ts # JWT access token strategy │ │ │ ├── auth.controller.ts # Auth endpoints (login, register, refresh) │ │ │ ├── auth.service.ts # Auth business logic │ │ │ ├── auth.module.ts # Auth module definition │ │ │ └── auth.constant.ts # Auth constants │ │ ├── users/ # Users module │ │ ├── app.controller.ts # Root controller │ │ ├── app.service.ts # Root service │ │ └── app.module.ts # Main application module │ └── main.ts # Application entry point ├── .env.example # Environment variables template ``` **Why did I choose this solution:** - Keeps code **organized by feature** (config, modules, etc.) - **Easy to maintain and scale** - Follows **NestJS best practices** ### b. Frontend Folder Structure (Next.js) **What solution did I choose?** ```bash saheb-frontend-skeleton/ ├── src/ │ ├── app/ │ │ ├── (dashboard)/dashboard/ │ │ │ ├── page.tsx # for example: server component │ │ │ └── _client.tsx # for example: client component │ │ └── login/ │ │ └── page.tsx # for example: login page │ ├── components/ │ │ └── ui/button.tsx # for example: UI component │ ├── i18n/ │ │ └── locales/en.json # for example: English translations │ ├── lib/ │ │ └── api-client.ts # for example: Axios setup │ └── store/ │ └── auth.ts # for example: Zustand auth store ├── public/ # Static assets ├── .env.example ├── Dockerfile └── next.config.ts ``` **Why did I choose this solution:** - **Make the page a server component by default** - Allows running **server-side logic before rendering the page** - Useful for **auth checks, data fetching, or redirection** ### C. Mobile Folder Structure (React Native + Expo) ```bash ─ assets/ # Images, icons, fonts, etc. ─ scripts/ # Build or helper scripts ─ src/ │ ├── app/ # App entry points / pages │ │ ├── _layout.tsx # Main layout for all screens │ │ ├── index.tsx # Home page │ │ ├── events.tsx # Events page │ │ └── settings.tsx # Settings page │ ├── components/ # Reusable UI components │ │ ├── Table/ │ │ │ ├── Cell.tsx # Example table cell │ │ │ └── index.tsx │ │ ├── BarChart.tsx │ │ └── Button.tsx │ ├── screens/ # Screens composed of components │ │ ├── Home/ │ │ │ ├── Card.tsx # Component used only in Home │ │ │ └── index.tsx # Home screen │ │ ├── Events.tsx # Events screen │ │ └── Settings.tsx # Settings screen │ ├── utils/ # Reusable helper functions │ └── hooks/ # Custom React hooks │ └── useTheme.ts ├── app.json # Expo config ├── eas.json # Expo EAS build config └── package.json # Dependencies ``` **Why did I choose this solution:** - **Pages are in `app/`** → follows **Expo Router rules** for automatic routing - **Folders in `app/`** → organize related pages together (stacks, tabs, etc.) - **`/screens/` folder** → keeps **page-specific components** separate and organized - **Easy to maintain and scale** → adding new pages or layouts is simple - **Clear separation of concerns** → components, hooks, utils, and assets are all in their own folders ## 3. Localization & Language Support ### a. Multi-language database translation strategy ##### 1. What solution did I choose? - - ##### **One-Table-Fits-All (global translation table):**
To fetch a product with translations, you need **at least 2 joins**
-Large translations table (all entities’ text in all languages) can become huge
-Requires proper indexing: `(id, language_code)` and `(language_code, value)` for fast lookup
-Caching may be needed for high-traffic
-Hard to maintain and Debug
##### 4. Alternatives ##### 1. Translation Table
Each entity has its own translation table (`product_translations`)
-Easy to understand, manage and debug with for any developer
-No magic IDs, no indirection
-Very safe data model
-One join only
##### 3. Cons: -**Schema Duplication:** Every translatable entity needs its own table
-Adding Fields Requires Schema Changes.
##### b. App language and RTL (Right-to-Left) support on web and mobile ##### What solution did we choose? **Mobile** - `react-i18next` for translations - `expo-localization` to detect device language - `I18nManager` for RTL handling - `NativeWind` for RTL-friendly styling **Web** - `next-intl` for internationalization - Built-in RTL support using **ShadCN UI** and **Radix UI** --- ##### Why did I choose this solution? - Shared translation concepts between web and mobile - Automatic language detection from the device or browser - Full support for **Arabic (RTL)** and **Latin (LTR)** layouts ## 4. Core Domain Logic ##### 1. Qibla Calculation Logic 1. ##### Purpose: - Calculate the **exact direction of the Kaaba** from the user’s location 2. ##### Technology Used: - **adhan-js** 3. ##### Why did I choose this option - Adhan is a well tested and well documented library for calculating Islamic prayer times in JavaScript using Node or a web browser - Provides Vriety of Calculation methods - Have Other related solutions (Prayers Time Calculation, Sunnah Times) 4. ##### Example: ```typescript var coordinates = new Coordinates(35.78056, -78.6389); var qiblaDirection = Qibla(coordinates); ``` 5. ##### key formula - ```ini rotationNeeded = qiblaDirection - phoneHeading ``` ##### 2. Prayer Time Calculation Methods 1. ##### Purpose - Calculate **daily prayer times** based on location and date. 2. ##### Technology Used: - **adhan-js** 3. ##### Why did I choose this option - Multiple calculation methods - Different madhabs - High astronomical accuracy - Support Manual Adjusments (adding for example 5 to each or specific prayer) 4. ##### Prayer Time Calculation Methods 1. **Muslim World League** Standard method used in many countries worldwide. 2. **Egyptian General Authority of Survey** Official method used in Egypt and some nearby regions. 3. **University of Islamic Sciences, Karachi** Commonly used in Pakistan, Bangladesh, and parts of India. 4. **Umm al-Qura University (Makkah)** Official method used in Saudi Arabia. 5. **Dubai** Method used in the UAE with regional time adjustments. 6. **Moonsighting Committee** Used mainly in North America, based on moon sighting criteria. 7. **North America (ISNA)** Standard method used by Islamic Society of North America. 8. **Kuwait** Method used by the Ministry of Awqaf in Kuwait. 9. **Qatar** Official method used in Qatar, similar to Umm al-Qura. 10. **Singapore** Method used in Southeast Asia with rounding rules. 11. **Tehran (Institute of Geophysics)** Method used in Iran with regional astronomical adjustments. 12. **Turkey (Diyanet)** Official Turkish religious authority method. 13. **Other / Custom** Allows manual configuration of calculation parameters. 5. ##### Supported Madhabs - **Shafi (Shafi‘i / Standard)** Used by the majority of Muslims worldwide Asr starts when an object’s shadow is **equal to its height** - **Hanafi** Commonly used in South Asia and parts of the Middle East Asr starts when an object’s shadow is **twice its height** 6. ##### Examples: 1. Full Example - ```typescript import { Coordinates, CalculationMethod, PrayerTimes, SunnahTimes, Prayer, Qibla, } from 'adhan'; import moment from 'moment-timezone'; const coordinates = new Coordinates(35.7897507, -78.6912485); const params = CalculationMethod.MoonsightingCommittee(); const date = new Date(); const prayerTimes = new PrayerTimes(coordinates, date, params); const sunnahTimes = new SunnahTimes(prayerTimes); moment(prayerTimes.fajr).tz('Africa/Casablanca').format('h:mm A'); ``` 2. Prayer time date adjustment example: - ```typescript const date = new Date(2015, 11, 1); const params = CalculationMethod.MuslimWorldLeague(); params.madhab = Madhab.Shafi; const p = new PrayerTimes(new Coordinates(35.775, -78.6336), date, params); console.log(moment(p.fajr).tz('America/New_York').format('h:mm A')); # 5:35 AM params.adjustments.fajr = 10; const p2 = new PrayerTimes(new Coordinates(35.775, -78.6336), date, params); console.log(moment(p2.fajr).tz('America/New_York').format('h:mm A')) # 5:45 AM ``` ##### 2. Hijri time caulculation methods 1. ##### Purpose - Convert Gregorian dates to **Hijri (Islamic) calendar.** 2. ##### Technology Used: - Native Intl API 3. ##### Why did I choose this option - - Multiple calculation methods - No external dependency - Good performance - Works on **modern browsers and mobile** 4. ##### Hijri Calculation Methods 1. `islamic` - Astronomical calculation (tabular-based) - Consistent and predictable - Common default in many environments 2. `islamic-umalqura` - Based on **Umm al-Qura calendar** - Official calendar used in **Saudi Arabia** - Most accurate for KSA 3. ##### `islamic-tbla` - Tabular Islamic calendar - Fixed, arithmetic-based - Does **not** follow moon sighting 4. ##### `islamic-civil` - Civil Islamic calendar - Simplified tabular system - Used mainly for civil/statistical purposes 5. **Example:** - ```typescript const hijriDate = new Intl.DateTimeFormat( "ar-SA-u-ca-islamic", { day: "numeric", month: "long", year: "numeric", } ).format(new Date()); console.log(hijriDate); ``` ## 6. Media Management ### 1. Audio resource handling (Sermon / موعظة) 1. ##### What solution did I choose? - **AWS S3** for hosting all audio content 2. ##### Why did I choose this solution? - - **AWS S3** for storing audio and video files - **CloudFront CDN (content delivery network)** for fast streaming and global delivery - Already using it on our apps - easy to test and debug with **Minio S3** ### 2. Video hosting and streaming strategy 1. ##### What solution did I choose? - **YouTube** for hosting all video content 2. ##### Why did I choose this solution? - Free and reliable hosting - Automatic **adaptive streaming** for all devices - Handles all **video encoding, formats, and resolutions** - Easy embedding in web/mobile apps - Already implemented with Maraqi 3. ##### Example from maraqi - [](https://italiano.embouzkoura.space/uploads/images/gallery/2026-01/screenshot-2025-12-24-11-02-21-001-com-maraqi-appmobile.jpg) 4. ##### Alternatives - Vimeo - AWS S3 ## 6. Notifications & Communication ### 1. Scheduling notificaiton 1. ##### Purpose - Keep users **engaged and informed for prayer times, acts...** - Deliver **timely updates** (push notifications, emails) - Support **daily schedules, prayer reminders, or app events** - Ensure notifications are **reliable, even if the app crashes** 2. ##### What solution did I choose? 1. ##### Technologies - **NestJS Cron** – scheduling jobs - **BullMQ (Redis-based queue)** – delayed job processing - **Expo Push Notifications / FCM / APNs** – mobile notifications - **Nodemailer / Email providers** – email notifications - **moment-timezone timezone library** for user timezone handling 2. ##### Implementation: - **NestJS Cron** runs every midnight - Cron **creates a BullMQ queue** for only **that day’s notifications** and based on the user timezone - Each notification in the queue has a **delay** for its scheduled time 3. ##### Why did I choose this solution? - Avoid running a **heavy cron every minute** - Node.js event loop **cannot handle large number of delayed notifications** directly - Using BullMQ queues allows: - **Reliable scheduling** - **Retry mechanisms** - Scalable background processing 4. ##### Logic Summary 1. At **midnight**, the cron job collects all notifications for the current day 2. Pushes them into a **BullMQ queue** with their **scheduled delay** based on user timezone 3. Worker processes the queue and sends the notification at the correct time 5. ##### Technical Challenges 1. Handling **large volume** of notifications without blocking Node event loop 2. Ensuring **notifications are sent even if the app or server restarts** 3. Avoiding **expensive cron runs** every minute/hour 4. Synchronizing **user timezones** for delivery ### 2. Timezone-Aware Push Notification System 1. ##### Purpose - Ensure notifications are delivered **at the correct local time** for each user - Support **global users in different timezones** - Maintain **reliability and accuracy** for time-sensitive events 2. ##### What solution did I choose? - - **Moment-timezone** – convert timezone to user local time - **Geo-TZ** – get timezone from latitude/longitude - **BullMQ** – queue and schedule delayed notifications 3. ##### Why did I choose this solution - Users may be in **different timezones**, so server time alone isn’t enough - Moment-timezone allows **precise conversion** of UTC times to user local time - Combined with BullMQ, notifications **fire at correct local time** without blocking server 4. Implementation Example: - ```typescript import * as moment from 'moment-timezone'; import { find } from 'geo-tz'; const latitude = 34.020882; const longitude = -6.841650; // Determine user's timezone from coordinates const timezones = find(latitude, longitude); const timezone = timezones[0] || 'UTC'; // Example: convert a UTC time to user's local time const utcTime = new Date('2026-01-02T12:00:00Z'); const localTime = moment(utcTime).tz(timezone).format('HH:mm'); console.log(`Notification should fire at local time: ${localTime}`); ``` ### 3. Email notification 1. ##### What solution did I choose - **NestJS MailerModule** integrated with **Mailgun API** - Emails are sent through **Mailgun’s transactional service** 2. ##### Technologies - **@nestjs-modules/mailer** – NestJS module for sending emails - **Mailgun** – Transactional email service with API/SMTP integration - **Handlebars** – for dynamic email templates - **BullMQ** – for queueing scheduled emails 3. ##### Why did I choose this solution? - Mailgun is Well known and used - NestJS Mailer is **well-integrated** with the framework - Easy to **use templates** for personalized content - Works seamlessly with **queues** for delayed or scheduled emails ## 7. Application Standards ### 1. Authentication and Authorization 1. ##### What solution did I choose - We chose a **Passport.js–based authentication system** using: - Local strategy for login - JWT access and refresh tokens - Separated strategies per user type (normal user / admin) - Different token storage strategies for web and mobile - RBAC for access control - ##### Technologies - **Passport.js** (NestJS integration) - **JWT (Access & Refresh Tokens)** - **bcrypt** (password and refresh token hashing) - **HTTP-only cookies (Web)** - **Expo Secure Store (Mobile)** 2. ##### Why did I choose this solution? - **Password Hashing**: Bcrypt with 10 salt rounds - **Refresh Token Hashing**: Stored as bcrypt hash in database - **HTTP-Only Cookies** (Web): Prevents XSS attacks - **Secure Cookies**: Enabled in production - **Crypted Storage** (Mobile)**:** `expo-secure-store` provides a way to encrypt and securely store key-value pairs locally on the device - **Token Rotation**: New refresh token on each refresh - **Single Session**: Old refresh token invalidated on new login - **RBAC**: manages user access to systems 3. ##### Breaking down the Authentication and Authorization design system - - User database design: -
