Overview

This project uses the following tech stack:

• Vite
• Typescript
• React Router v7 (all imports from react-router instead of react-router-dom)
• React 19 (for frontend components)
• Tailwind v4 (for styling)
• Shadcn UI (for UI components library)
• Lucide Icons (for icons)
• Convex (for backend & database)
• Convex Auth (for authentication)
• Framer Motion (for animations)
• Three js (for 3d models)

All relevant files live in the 'src' directory.

Use bun for the package manager.

Keep src/convex/_generated in version control. The frontend build needs these Convex TypeScript bindings, so they must be available in clean deployment environments such as Vercel.

Setup

This project is set up already and running on a cloud environment, as well as a convex development in the sandbox.

Environment Variables

The project is set up with project specific CONVEX_DEPLOYMENT and VITE_CONVEX_URL environment variables on the client side.

The convex server has a separate set of environment variables that are accessible by the convex backend.

Currently, these variables include auth-specific keys: JWKS, JWT_PRIVATE_KEY, and SITE_URL.

Google sign-in also requires GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET in the Convex deployment environment (set them with npx convex env set). In Google Cloud Console, add the Convex site URL callback https://<your-deployment>.convex.site/api/auth/callback/google as an authorized redirect URI. Never put these server credentials in a VITE_ variable.

Using Authentication (Important!)

You must follow these conventions when using authentication.

Convex Auth is already set up for email one-time codes and anonymous sessions;

Google OAuth is also enabled.

All Convex authentication functions are already set up. Email OTP delivery is configured in src/convex/auth/emailOtp.ts and uses the Hostinger relay documented in hostinger-mailer/README.md.

src/convex/auth.ts declares the enabled providers. src/convex/auth.config.ts contains the Convex token issuer configuration.

Using Convex Auth on the backend

On the src/convex/users.ts file, you can use the getCurrentUser function to get the current user's data.

Using Convex Auth on the frontend

The /auth page supports Google OAuth and email OTP (which signs in existing accounts or creates an account for a new email). Navigate to /auth for all log in / sign up sequences.

Temporary anonymous test deployment

Use a separate Convex deployment and database for external testers; never point the public test build at the production Convex deployment. On the test Convex deployment, set NOUR_DEMO_MODE=true to disable Google and email authentication at the backend. Set NOUR_DEMO_MODE=false or remove it from the normal deployment to keep the regular sign-in methods enabled.

For the separate Vercel test project, set VITE_DEMO_MODE=true and VITE_CONVEX_URL to the test Convex deployment URL. Only anonymous sign-in is shown in this mode. Test data is still saved in the test database, so testers must not enter real personal or sensitive information. After testing, disable the test deployment and delete its Convex project/data when no longer needed.

Cycle tracking

Cycle days and selected observations are stored in Convex against the authenticated user, and the backend only returns or changes records belonging to that user. New accounts start with an empty calendar. Late-cycle estimates are shown only after at least three recorded period starts; they are informational, not medical advice. Optional browser notifications require permission and can only be delivered while the app is open. Users can select a continuous period range and attach a private note to an individual date; both are stored on the same account-scoped cycle records. The separate Notes tab stores personal notes against the signed-in account. Newly added notes show a sidebar indicator until the Notes tab is opened.

The dashboard navigation presents the overview, prayer/Quran/science planning, cycle tracking, personal notes, and reminder settings as separate views. The Al-‘Udhr switch is available in the sidebar and hides prayer slots in the planner.

Prayer times can be calculated from the device's location using the free AlAdhan API. Location permission is requested only after the user selects "Utiliser ma position"; coordinates and calculation preferences stay in browser storage, while coordinates are sent to AlAdhan to retrieve timings. These calculated times may differ from a specific mosque's timetable.

Morning and evening adhkar progress is also saved per authenticated user and calendar day. The next invocation stays locked until the required repetitions for the current one are recorded. Arabic text, transliteration, meanings, and source references are maintained in src/convex/adhkarData.ts.

The Al-Qur’an area keeps a per-account reading journal with passages, page or verse references, and personal notes. The Science bénéfique area records lessons from courses or books, their source or link, and study notes. The Planning area remains the daily schedule and prayer-time view. Journal entries include a date and time and automatically appear in the day and week planner; the corresponding generic default activity is hidden on dates with a journal entry. From the week planner, journal sessions can be rescheduled or removed, with changes reflected in their journal and planner entry together. On the overview, up to six shortcut blocks can be added, removed, and reordered. The Planning view also has day and week modes; activities can be added, rescheduled, moved between days, or removed. Shortcut preferences and planner activities are stored in this browser, while prayer times remain calculated separately from the user's location and method settings.

You MUST use this hook to get user data. Never do this yourself without the hook:

여기까지가 README 앞부분입니다. 나머지는 원문에서 읽을 수 있습니다. README 전문 보기 ↗