# Ihjaz — Complete Application Knowledge Base

> This file is the complete knowledge base for the **Ihjaz** application. It is intended to be read by AI assistants, crawlers, and anyone who needs a full understanding of what the app does and how every feature works from a user perspective.

---

## What Is Ihjaz?

**Ihjaz** (إحجز) is an appointment-booking platform that connects users with local businesses and service providers. The name means "reservation" or "booking" in Arabic.

The platform serves three types of actors:

| Role | Description |
|---|---|
| **Regular User (Customer)** | Discovers businesses on a map, books appointments, tracks their reservations |
| **Business Owner / Staff** | Manages one or more places, controls schedules, handles appointments, invites staff, views earnings |

---

## User Roles and How to Become Each

### Regular User
Any person who registers on the app is a regular user by default. They can search for places, book appointments, and manage their own reservations.

### Business Owner
A verified user who has been approved as a business can create and manage "places" (service locations). To become a business owner:
1. The user must first **verify their account** (phone number verified).
2. From the Profile page, they tap "Become a Business Account."
3. They upload an **identity document** (e.g., national ID or business license).
4. An admin reviews and **approves or rejects** the submission.
5. Once approved, the user gains access to the Business dashboard.

### Staff Member
A business owner can invite other registered users as staff for a specific place. Staff members see that place in their own app under the Business section with a "Staff" badge, and their permissions are limited to what the owner has granted.

---

## Application Structure

The application is a single web app used by regular users and business owners.

---

## Main App — Page-by-Page Features

### 1. Home Page (`/`)

The home (landing) page is the first screen users see.

**What it shows:**
- The **Ihjaz logo** and branding.
- A headline and subtitle explaining the app's purpose.
- For **unauthenticated users**: two action buttons — "Log In" and "Register."
- For **authenticated users**: a "Get Started" button (redirects to the Map), plus a **Recent Places** section showing the last places the user visited.

---

### 2. Authentication (`/login`, `/register`)

#### Login

Users can log in with:
- **Phone number or email** + password.
- **Google account** (one-tap sign-in).

**Workflow — Standard Login:**
1. Enter phone number or email.
2. Enter password (with show/hide toggle).
3. Click "Sign In."
4. If the account has **Two-Factor Authentication (2FA)** enabled, a TOTP verification step appears — the user must enter the 6-digit code from their authenticator app.
5. On success, the user is redirected to the Map page (or to the page they were originally trying to access).

**Forgot Password:**
A "Forgot password?" link opens a dialog where the user enters their email or phone. They receive a reset link/code to regain access.

#### Registration

Registration is a multi-step process:

1. **Step 1 — Name:** Enter display name. Optionally sign up with Google (which pre-fills name and email).
2. **Step 2 — Password:** Create a secure password.
3. **Step 3 — Phone Number:** Enter a phone number. This number will be used for verification.
4. **Step 4 — OTP Verification:** A one-time code is sent to the provided phone number. The user enters it to confirm their identity and complete registration.

After successful registration, the user is automatically logged in and redirected.

---

### 3. Map Page (`/map`)

The map is the **main discovery screen** — the heart of the app for regular users.

**Features:**
- An interactive map showing **place markers** for registered businesses nearby.
- A **search bar** at the bottom that expands to show results.
- A **"My Location" button** (GPS icon) to pan the map to the user's current position.
- A **filter button** to filter visible places by **place type** (e.g., clinic, barbershop, restaurant).
- **Recent places** appear when the search bar is expanded and no query is typed (for logged-in users).
- Selecting a place marker or search result shows a **Place Bottom Sheet** (a slide-up card with place details and a "Book" button).

**Searching:**
- As the user types, results appear live (with debounce).
- Results can include both registered app places and geocoded address results.
- Selecting a geocoded result pans the map to that location.

---

### 4. Place Detail Page (`/places/:id`)

Tapping a place on the map or navigating directly opens its full detail page.

**Information displayed:**
- Place photo and cover photo.
- Name, type, and address.
- Phone number (tap to call).
- **Opening hours** — shown in a formatted schedule.
- Location on a small embedded mini-map with a "Navigate" button to open the user's preferred maps app.
- **Star rating** (average) and number of reviews.
- A list of user reviews with ratings.

**Actions:**
- **Book an Appointment** — navigates to the booking page (if the place is open).
- **Share** — shares a link to the place.
- **Review** — if the user has had a completed appointment at this place, they can submit a star rating (1–5 stars).

**Blocked user behavior:**
- If a business owner has blocked a user, that user sees an "Access Denied" message when trying to view or book at that place.

---

### 5. Appointment Booking (`/places/:id/book`)

The booking page allows users to schedule an appointment with a business.

**Workflow:**

1. **Select a Date** — A horizontal scroll of the next 30 days is shown. Days on which the business is closed (based on its opening hours) are greyed out.
2. **Select a Time Slot** — Available time slots for the chosen day are shown as cards. Slots that have already passed (for today) are automatically disabled.
3. **Confirm** — A bottom sheet slides up showing the selected date and time.
4. **Intake Form (if required)** — If the business has configured a custom intake form, it appears as a dialog/sheet before finalizing the booking. The user must answer the required questions.
5. **Authentication gate (guests)** — If the user is not logged in, they are prompted to either log in or continue as a guest (entering only a name and phone number).
6. **Confirmation** — The appointment is created and the user sees a success state.

**Guest bookings:**
Users who book without an account receive a special **guest token link** (e.g., via SMS or displayed on screen) that they can use to view their appointment status and queue position without logging in.

---

### 6. My Appointments (`/appointments`)

> Requires authentication.

Shows a list of all appointments the user has booked.

**Each appointment card displays:**
- Business photo, name.
- Scheduled date and time (converted to the user's local timezone).
- A countdown ("in 2 days", "in 3 hours", "Starting soon").
- A **status badge**: Pending, Confirmed, Completed, Cancelled, No-show.

**Actions:**
- **Cancel** — available for appointments with "Pending" or "Confirmed" status. A confirmation dialog appears before cancellation.
- Infinite scroll loads older appointments as the user scrolls down.

---

### 7. Guest Appointment View (`/appointments/guest?token=...`)

Allows guests (users without an account) to view their specific appointment using a unique token link.

**Displays:**
- Business photo, name.
- Appointment date, time, and status.
- Countdown until the appointment.
- A link to view the queue position.

---

### 8. Guest Queue Page (`/queue/guest?token=...`)

Shows the guest's **current position in the queue** for their appointment.

**Displays:**
- Queue position number.
- Business name.
- A "Refresh" button to update the position in real time.
- If the queue feature isn't available, a helpful message is shown with an option to view the appointment details instead.

---

### 9. Notifications (`/notifications`, `/notifications/:id`)

> Requires authentication.

The notifications center shows all activity related to the user's appointments and business.

**Notification types include:**
- Appointment confirmed by business.
- Appointment cancelled.
- New staff invitation received.
- Appointment status updates.

**Features:**
- Unread count badge on the notification bell icon in the navigation.
- **Mark All as Read** button (appears when there are unread notifications).
- Tapping a notification opens its detail page.
- Infinite scroll for older notifications.

---

### 10. Profile Page (`/profile`)

> Requires authentication.

The profile page is where users manage their personal account settings.

**Sections:**

#### Pending Staff Invitations Banner
If the user has been invited to join a place as staff, a highlighted banner appears at the top with a "View" button linking to notifications.

#### Personal Information
- **Profile photo** — tap to upload a new photo (up to 5MB).
- **Display name** — edit and save.
- **Email** — view current email; tap "Change" to initiate an email change flow (requires OTP verification to the old and new email).
- **Phone number** — view current phone; tap "Change" to initiate a phone change flow (requires OTP verification).
- **Phone Verification** — if the phone is not yet verified, a section appears to request and enter an OTP.

#### Language
A language switcher (e.g., Arabic / English) that changes the entire app's language instantly.

#### Theme
A dark mode / light mode toggle.

#### Two-Factor Authentication (2FA)
Users can enable TOTP-based 2FA on their account. The setup shows a QR code to scan with an authenticator app (e.g., Google Authenticator).

#### Google Calendar
Users can connect their Google Calendar account so appointments are synced automatically.

#### Business Account
If the user's account is verified (phone confirmed), a "Become a Business Account" card appears:
- If not yet applied: shows a "Get Started" button that opens the verification sheet.
- If pending approval: the button is disabled with a "Pending" label.
- If approved: shows a "Manage" button that goes to the Business dashboard.
- If rejected: the user can resubmit.

#### Customer Support
- A "Contact Support" button opens a support chat/form sheet.
- A "Terms & Conditions" button opens the terms page in a browser tab.

#### Sign Out
A logout button with a confirmation dialog.

---

### 11. Business Dashboard (`/business`)

> Requires authentication + approved business account.

The main hub for business owners and staff.

**What it shows:**
- A stats card: "Your Places" — showing how many places the user has created out of the allowed maximum (5).
- Remaining slots counter.
- An "Add New Place" button (disabled if the maximum is reached).
- A list of all places owned by (or shared with) the user as staff.

**Each place card shows:**
- Cover photo and place logo/photo.
- Name, type, address.
- A "Staff" badge if the current user is a staff member (not the owner).
- An action button (three-dot menu on desktop, or tap-to-open bottom sheet on mobile) with options:
  - **Edit place** — open the edit dialog.
  - **Appointments** — go to the appointment calendar.
  - **Schedule** — edit opening hours.
  - **Staff** — manage staff members.
  - **Intake Form** — configure the custom intake form.
  - **Blocked Users** — view and manage blocked users.
  - **Earnings** — view revenue and transactions.
  - **Subscription** — manage the subscription plan.
  - **QR Code** — generate and share a QR code linking to the place's booking page.
  - **Delete** — permanently delete the place (with confirmation).

**Creating/Editing a Place:**
A dialog opens with fields:
- Place name.
- Place type (selected from a list managed by admins).
- Address.
- Phone number.
- Profile photo.
- Cover photo.
- Opening hours (via the opening hours editor).

---

### 12. Appointment Calendar (`/business/places/:id`)

A monthly calendar view showing all appointments for a specific place.

**Features:**
- Month navigation (previous/next arrows).
- Days with appointments show a highlighted dot/indicator and count.
- Tapping a day navigates to the **Day Appointments** page for that date.

---

### 13. Day Appointments (`/business/places/:id/d/:date/appointments`)

Lists all appointments for a specific day in detail.

**Each appointment shows:**
- Customer name and photo.
- Scheduled time.
- Status badge.
- Intake form answers (if any) submitted by the customer.

**Actions (for the owner/authorized staff):**
- **Confirm** — confirm a pending appointment.
- **Complete** — mark as completed.
- **Cancel** — cancel the appointment.
- **Block User** — block the customer from making future bookings at this place.
- **New Appointment** — create a new appointment manually.

---

### 14. Create Business Appointment (`/business/places/:placeId/new`)

Allows the business owner or staff to manually book an appointment on behalf of a user.

**Two modes:**

**Mode 1 — For a Registered User:**
1. Search for a user by name or phone number.
2. Select the user from results.
3. Select a date from the next 30 days.
4. Select an available time slot.
5. Confirm and create the appointment.

**Mode 2 — For a Guest:**
1. Switch to "Guest" mode.
2. Enter the guest's name and phone number.
3. Select a date and time slot.
4. Confirm and create the appointment.

---

### 15. Opening Hours Editor (`/business/places/:id/timesslotes`)

Allows the business owner or authorized staff to configure when the place is open.

**Features:**
- Toggle each day of the week (Monday–Sunday) as open or closed.
- For each open day, add one or multiple time slot ranges (e.g., 09:00–12:00, 14:00–18:00).
- Save changes with a "Save" button.
- Changes immediately affect which time slots are available during booking.

---

### 16. Staff Management (`/business/places/:id/staff`)

> **Subscription-gated feature** — requires a subscription plan with the Staff Management feature enabled. If the current plan does not include staff management, a locked screen is shown with an "Upgrade" call to action.

Allows business owners to invite and manage team members for a specific place.

**Staff Permissions (granular):**

| Permission | What it grants |
|---|---|
| View Appointments | View the appointments calendar and list |
| Manage Appointments | Confirm, complete, cancel appointments |
| Manage Blocked Users | Block and unblock users |
| Manage Schedule | Edit opening hours |
| View Earnings | View earnings and transactions |
| Manage Employees | Invite and remove other staff |

**Inviting Staff:**
1. Navigate to the Staff page.
2. Click "Invite Staff."
3. Enter the invitee's **email or phone number**.
4. Select which permissions to grant.
5. Send the invitation.

**Invitation States:**
- **Pending** — invitation sent, waiting for the invitee to accept.
- **Accepted** — the invitee accepted and is now active staff.
- **Rejected** — the invitee declined.

The owner can **remove** any pending or accepted invitation at any time (with a confirmation prompt).

**Accepting a Staff Invitation (from the invitee's side):**
- The invitee receives a notification in the app.
- They can accept or reject from the Notifications page.
- Once accepted, the place appears in their Business dashboard with a "Staff" badge.

---

### 17. Custom Intake Form (`/business/places/:id/intake`)

> **Subscription-gated feature** — requires a subscription plan with the Intake Form feature enabled. If not enabled, a locked screen is shown with an "Upgrade" prompt.

Business owners can create a custom form that customers must fill out before completing a booking.

**Supported Field Types:**
- **Text** — a free-text input.
- **Dropdown** — the customer selects one option from a list.
- **Radio** — the customer picks one option from a visible set.
- **Date** — the customer picks a date.

**Building the form:**
1. Click "Add Field."
2. Enter a field label (the question text).
3. Choose the field type.
4. For dropdown and radio fields: add options one by one by typing the option text and pressing Enter or clicking "Add." Duplicate options are rejected.
5. Toggle "Required" to make the field mandatory.
6. Fields can be reordered or deleted.
7. Click "Save" to persist the form.

**During booking:**
If the place has an intake form configured, it appears to the customer as a dialog step during the booking flow before they confirm. Required fields must be filled in. The answers are stored with the appointment and visible to the business owner in the day appointments view.

---

### 18. Blocked Users (`/business/places/:id/blocked`)

A list of all users who have been blocked from booking at a specific place.

**Each entry shows:**
- User photo, name, and phone number.
- The date they were blocked.
- An "Unblock" button.

Clicking "Unblock" shows a confirmation dialog before removing the block.

---

### 19. Earnings (`/business/places/:id/earnings`)

A financial overview for a specific place.

**Summary cards:**
- **Total Earnings** — all-time accumulated revenue.
- **Current Balance** — balance available for withdrawal.

**Transaction history:**
- An infinite-scrolling list of all transactions.
- Each row shows: date, amount (in DZD — Algerian Dinar), type, and status (Completed, Pending, Failed).

---

### 20. Subscriptions (`/subscriptions/:placeId`)

> Requires authentication.

The subscription management page for a specific place.

**What it shows:**
- The **currently active plan** (if any), including: plan name, status, billing cycle, period dates, appointment usage vs. limit, and days remaining.
- All **available subscription plans** with features, pricing (monthly and yearly), and a comparison.

**Plan actions:**
- **Start Free Trial** — if a plan offers a free trial and the place hasn't used one before, a one-click trial activation is available.
- **Subscribe** — initiates a checkout flow via the Chargily payment gateway (Algerian payment). The user selects monthly or yearly billing and is redirected to a payment page.
- **Upgrade / Downgrade** — switching between plans mid-cycle shows a proration dialog with the credit earned from the current plan and the charge for the new plan.
- **Apply Promo Code** — a text field where users can enter a discount code before subscribing. Valid codes show the discounted price.
- **Cancel Subscription** — cancels the current subscription after a confirmation dialog.

**Subscription statuses:**
- `active` — currently active and paid.
- `trial` — in a free trial period.
- `expired` — subscription period ended.
- `cancelled` — cancelled by the user.
- `inactive` — not currently subscribed.

**After payment:**
The user is redirected to the Subscription Status page which polls the payment gateway and shows:
- **Success** — plan details and a link back to the business dashboard.
- **Failed / Expired / Cancelled** — error message with a retry button.

---

### 21. Business Verification (`/business/verify`)

A dedicated page where users can submit or check their business verification status.

**States:**
- **Not Applied** — shows an upload button to submit an identity document (max 5MB).
- **Pending** — shows a "Verification Pending" message with a clock icon.
- **Approved** — shows a green checkmark and "Verified Business" message.
- **Rejected** — shows a red X with a message, and allows the user to re-submit.

---

## Key User Journeys

### Journey 1: A New User Books Their First Appointment

1. Opens the app → sees the Home page.
2. Taps "Register" → completes the 4-step registration (name → password → phone → OTP).
3. Redirected to the Map page.
4. Searches for a business type or uses the type filter.
5. Taps a place marker → reads details in the bottom sheet.
6. Taps "Book" → navigates to the booking page.
7. Selects a date → selects a time slot.
8. If the business has an intake form, fills it out.
9. Confirms → appointment is created.
10. Views the appointment in "My Appointments."

---

### Journey 2: A Business Owner Sets Up Their Place

1. Registers and verifies their account (phone verified).
2. Goes to Profile → taps "Become a Business Account" → uploads an identity document.
3. Once the account is approved, opens the Business dashboard.
4. Taps "+ Add New Place" → fills in place details (name, type, address, photos, opening hours).
5. The place is published and appears on the map for all users.
6. Purchases a subscription plan to unlock advanced features.
7. Sets up a custom intake form (requires an intake-enabled subscription).
8. Invites a staff member (requires a staff-enabled subscription).

---

### Journey 3: A Staff Member Handles Appointments

1. Receives a staff invitation notification → accepts it.
2. Opens the Business dashboard → sees the place with a "Staff" badge.
3. Taps the place → opens the appointment calendar.
4. Taps a date with appointments → sees the day's appointments list.
5. Confirms pending appointments, marks completed ones as done.
6. Manually books a walk-in appointment using "New Appointment."

---

### Journey 4: A Guest Books Without an Account

1. Someone shares a direct booking link to a place.
2. Opens the booking page → selects a date and time.
3. Prompted to log in or continue as guest → enters name and phone number.
4. Completes any intake form questions.
5. Appointment is created → receives a guest token link.
6. Uses the token link anytime to check appointment status and queue position.

---

## Multilingual Support

The entire application supports multiple languages:
- **Arabic (AR)** — with full right-to-left (RTL) layout support.
- **English (EN)** — the default language.

Users can switch languages from the Profile page. The language switcher is also available on the Login and Register pages.

---

## Real-Time Updates

The application uses WebSocket connections to deliver real-time updates without requiring a page refresh:
- Appointment status changes appear instantly in the app.
- New notifications are delivered in real time.
- Queue position data can be refreshed on the guest queue page.

---

## Theme Support

The app supports **dark mode** and **light mode**. Users can switch themes from their Profile page. The preference is saved and persists across sessions.

---

## Platform Availability

The Ihjaz app is available as:
- A **web application** — accessible from any modern browser.
- A **mobile app** (Android) — installed as a native app via APK or app store.
- A **desktop app** (Windows/macOS via Electron) — a native desktop application with a custom title bar and native window controls.

The experience adapts slightly per platform (e.g., the desktop version shows native window controls), but all features are available across all platforms.

---

## Payment & Currency

- The platform uses **DZD (Algerian Dinar)** as the currency.
- Payments for subscriptions are processed via **Chargily** — an Algerian payment gateway.
- After initiating a subscription purchase, the user is redirected to Chargily's secure checkout page and then returned to the app with a payment status confirmation.

---

*This file reflects the complete feature set of the Ihjaz application as documented at the time of the last audit.*