# Majarrah (majarrah.io) - Full AI Reference

> Not to be confused with the Arabic content subscription platform of the same name. This is majarrah.io — an AI decision engine for Saudi Arabia real estate, not a media or publishing service.

## Product overview

Majarrah (majarrah.io) is an AI decision engine for Saudi Arabia real estate. It is not a listings aggregator. The product's core positioning: help buyers make a confident, data-backed purchase decision. Every buyer interaction is centered on a "decision" - a unit of AI-powered analysis grounded in verifiable data from the Saudi Ministry of Justice (MOJ).

Base URL: https://majarrah.io (canonical https://www.majarrah.io)
MCP endpoint: https://majarrah.io/api/mcp
Auth: OAuth2.1 + PKCE for end-user MCP access; static Bearer for admin MCP
Default locale: ar (Arabic, RTL)
Supported locales: ar, en
Arabic product name: مچرة

---

## Roles

### Buyer
A person in Saudi Arabia shopping for, comparing, or planning to purchase residential or investment real estate. Core desire: make a correct decision, not just find listings. Buyers interact via the public site, AI agent chat, and MCP connector.

### Broker
A FAL-licensed real estate agent. Lists properties, fields buyer inquiries, schedules viewings, closes deals. Verified by their FAL (REGA license) and CR (Commercial Registration). Operates a team workspace. Has a public profile page at `/broker-public/[handle]`.

### Developer
A real estate developer. Showcases off-plan projects to buyers. Operates an AI chat widget on their own website. Manages leads, uploads knowledge base documents, reads analytics. Has a public portal at `/developer/[slug]`. Developer subdomains are auto-provisioned via Vercel API (`{slug}.majarrah.io`).

### Admin
Internal Majarrah team. Manages developers, projects, broker workspaces, listing moderation, FAL/CR verification, WhatsApp devices, ghost brokers, and investor access tokens.

---

## Buyer features

- **AI Decision Engine** (conversational, bilingual AR/EN) - natural language property search with top-5 recommendations and reasoning
- **Property analysis cards** - AI score (0-100), verdict (Excellent/Good/Average/Weak / ممتاز/جيد/متوسط/ضعيف), bilingual AI bullet analysis points
- **Risk detection flags** - overpriced, stale listing, high development activity
- **Price intelligence** - asking price vs MOJ neighborhood median SAR/sqm, yield estimate, % above/below market
- **AI Decision Reports** - 6 report types: valuation, investment, comparison, neighborhood, land analysis, shareable public link (via `share_token`)
- **Property discovery** - search and filter by city, district, type, price, area, beds
- **Property detail pages** - full listing with title EN/AR, price, area, beds, baths, images, AI bullets
- **Viewing bookings** - schedule a viewing with a FAL-licensed broker; broker confirms or cancels
- **Inquiry messaging** - ask a broker a question; threaded replies
- **Phone reveal** - reveal broker's phone number (costs 1 lead credit from the broker's workspace)
- **Saved properties** - bookmark listings (stored as `buyer_signals` with `signal='saved'`)
- **Verified brokers** - browse FAL-confirmed brokers with public profiles
- **Decision packs** - purchase AI usage in packs of 5, 20, or 50 decisions via Geidea payment
- **Post-viewing survey** - structured feedback after a viewing appointment

---

## Broker features

- **Workspace** - team workspace (roles: owner, admin, agent, viewer)
- **Property listings CRUD** - create, edit, publish, delete listings with AI description generation (bilingual)
- **Listing moderation** - statuses: `pending`, `approved`, `auto_approved`, `rejected`; FAL-verified workspaces get `auto_approved` bypass
- **Inquiry inbox** - threaded buyer-to-broker messaging with AI-drafted reply suggestions
- **Viewing calendar** - confirm, cancel, or complete viewing appointments; configure availability (days + time slots)
- **CRM pipeline** - kanban stages: New → Contacted → Viewing Scheduled → Offer Made → Won / Lost
- **CRM lead sources** - Direct, WhatsApp, Website, Referral, Social, Inquiry, Visit, Manual
- **CRM activities, notes, tasks** - full lead activity log per CRM lead
- **AI-qualified leads** - buyers pre-screened by AI agent before reaching the broker
- **FAL verification** - submit license number + image; admin reviews, approves or rejects with team notification
- **CR verification** - submit Commercial Registration; admin reviews
- **WhatsApp integration** - GoWA device connection; WA-verified status badge; broker-buyer WA flows
- **Public broker profile** - configurable public page at `/broker-public/[handle]`
- **Billing** - lead credit packs (one-time Geidea purchase); subscription plans (max listings, monthly credit grant, AI queries/day)
- **Bulk property import** - upload multiple listings at once
- **API keys** - generate API keys for external integrations and the Decisions API
- **AI dashboard narrative** - AI-generated workspace performance summary
- **AI agent chat** - broker-context AI assistant
- **Team management** - invite and manage workspace members
- **Real-time notifications** - in-app notification bell

---

## Developer features

- **Developer profile** - name EN/AR, slug, logo, website, contact email; public portal at `/developer/[slug]`
- **Off-plan projects** - create and manage projects (name EN/AR, city, delivery year, starting price SAR, WAFI/escrow number, lat/lng, images, published flag)
- **AI chat widget** - embeddable JS widget for the developer's own website; fully branded
- **Widget configuration** - display name, avatar, colors, theme, bubble color, welcome messages, suggested messages, footer text, system prompt override, lead capture fields, hide-branding option
- **Knowledge base** - upload PDF/text documents; content is chunked and embedded via pgvector for the widget AI to answer questions from
- **Widget inbox** - view all visitor chat sessions, read transcripts, add internal notes, send human replies, assign to team member, close sessions
- **Lead capture** - widget sessions capture contact name, phone, email, budget, bedroom preference; links to CRM lead
- **CRM for developers** - manage leads generated via widget or public portal
- **Developer plans** - subscription plans define: `conversations_monthly`, `knowledge_base_docs`, `team_members_limit`, `has_widget`, `has_crm`, `has_api`, `has_analytics`, `whatsapp_numbers`
- **Developer billing** - plan subscriptions + addon subscriptions via Geidea
- **Analytics** - buyer interest and widget performance tracking
- **Team management** - developer team roles and invites
- **API keys** - for external integrations
- **WhatsApp settings** - per-developer WhatsApp configuration

---

## Admin features

- Developer account creation, editing, user invitations
- Project management on behalf of developers
- Listing moderation queue (approve/reject; rejection sends notification to seller)
- Bulk AI score backfill (recompute `ai_score` + `ai_verdict` for unscored properties)
- Bulk embedding backfill (re-embed published properties for semantic search)
- Workspace management (assign account managers to broker workspaces)
- Ghost broker management: admin-created unlicensed property pools; generate claim invites; send claim emails with time-limited tokens
- FAL verification queue (approve → workspace `fal_status` updated, all members notified)
- CR verification queue
- WhatsApp device management via GoWA (register slot, generate QR, poll connection status, disconnect)
- Investor token management (gate access to `/financial-model` and `/one-pager` pages)
- Revenue and payments visibility
- Platform conversations overview

---

## MCP tool surface

**Endpoint**: `POST https://majarrah.io/api/mcp` (also routed at `https://api.majarrah.io/mcp`)
**Transport**: Streamable HTTP, JSON-RPC 2.0, stateless per-request
**Auth**: OAuth2.1 + PKCE for end users; `Authorization: Bearer <MCP_ADMIN_SECRET>` for admin access
**OAuth discovery**: `https://majarrah.io/.well-known/oauth-authorization-server`
**Dynamic client registration**: `POST https://majarrah.io/oauth/register` (RFC 7591)
**Protected resource metadata**: `https://majarrah.io/.well-known/oauth-protected-resource` (RFC 9728)

### Shared (all authenticated roles)
- `whoami` - returns identity, roles, workspaces, developer memberships
- `ping` - health check, echoes message

### Buyer tools
- `buyer_search_properties` - search catalog (q, city, district, price/area/beds range, limit/offset)
- `buyer_get_property` - full property detail by id
- `buyer_list_saved_properties` - list saved/bookmarked properties
- `buyer_save_property` - save a property
- `buyer_unsave_property` - remove saved property
- `buyer_reveal_broker_phone` - reveal broker phone number (charges 1 lead credit from the broker's workspace)
- `buyer_price_intel` - MOJ benchmark: median SAR/sqm + % above/below median for a given location and property type
- `buyer_submit_inquiry` - submit an inquiry to a broker about a property
- `buyer_get_inquiry` - get inquiry details + message thread
- `buyer_list_inquiries` - list the buyer's inquiries
- `buyer_reply_inquiry` - add a message to an inquiry thread
- `buyer_book_viewing` - book a viewing appointment (scheduled_at, user_phone)
- `buyer_list_bookings` - list the buyer's viewing bookings
- `buyer_cancel_booking` - cancel a viewing

### Broker tools
- `broker_list_properties` - list workspace properties (filter by moderation status)
- `broker_get_property` - detail for one workspace property
- `broker_create_property` - create a listing (enters moderation queue)
- `broker_update_property` - update a listing
- `broker_delete_property` - delete a listing
- `broker_list_inquiries` - list workspace inquiries (filter by status)
- `broker_get_inquiry_thread` - full message thread for an inquiry
- `broker_reply_inquiry` - reply to a buyer inquiry
- `broker_close_inquiry` - close/resolve an inquiry
- `broker_list_bookings` - list workspace viewing bookings
- `broker_confirm_booking` - confirm a viewing
- `broker_cancel_booking` - cancel a viewing
- `broker_complete_booking` - mark a viewing as complete
- `broker_list_crm_leads` - list CRM leads (filter by stage, source)
- `broker_create_crm_lead` - create a new CRM lead
- `broker_update_crm_lead` - update lead stage, source, or details
- `broker_get_workspace` - get workspace info (name, handle, FAL status, subscription)
- `broker_update_workspace` - update workspace settings
- `broker_list_members` - list workspace team members
- `broker_invite_member` - invite a team member
- `broker_list_api_keys` - list API keys
- `broker_create_api_key` - create a new API key

### Developer tools
- `developer_get_profile` - get developer profile
- `developer_update_profile` - update developer profile
- `developer_list_projects` - list off-plan projects
- `developer_get_project` - project details
- `developer_create_project` - create a new project
- `developer_update_project` - update project info
- `widget_get_settings` - get widget configuration
- `widget_update_settings` - update widget configuration
- `widget_list_kb` - list knowledge base entries (grouped by title)
- `widget_delete_kb` - delete KB entries by ids
- `widget_list_inbox` - list widget chat sessions
- `widget_get_session` - session transcript + all messages
- `widget_reply_session` - send a human reply into a session
- `widget_close_session` - close a session
- `widget_add_note` - add internal note to a session
- `widget_assign_session` - assign session to a team member
- `developer_list_team` - list developer team members
- `developer_invite_team` - invite a team member
- `developer_list_api_keys` - list API keys
- `developer_create_api_key` - create a new API key

### Admin tools
- `admin_list_developers` / `admin_create_developer` / `admin_update_developer` / `admin_invite_developer_user`
- `admin_list_projects` / `admin_create_project` / `admin_update_project`
- `admin_list_listings` (filter by `moderation_status`) / `admin_moderate_listing` (approve/reject) / `admin_property_action`
- `admin_list_workspaces` / `admin_assign_account_manager`
- `admin_list_ghost_brokers` / `admin_send_ghost_invite`
- `admin_list_fal_verifications` / `admin_moderate_fal_verification` (approve/reject + notify all workspace members)
- `admin_list_cr_verifications` / `admin_moderate_cr_verification`
- `admin_whatsapp_register` / `admin_whatsapp_get_qr` / `admin_whatsapp_status` / `admin_whatsapp_disconnect`
- `admin_list_investor_tokens` / `admin_create_investor_token` / `admin_delete_investor_token`
- `admin_backfill_ai_scores` - recompute AI scores for unscored properties
- `admin_backfill_embeddings` - re-embed published properties (force flag supported)

---

## External / API-key Decisions API

For third-party integrations (broker API keys):

- `POST /api/v1/decisions` - run a decision against a property (scoring or reasoning mode)
- `GET /api/v1/locations` - list supported cities and districts

Scoring mode (1 decision): returns score, verdict, per-bucket breakdown instantly.
Reasoning mode (3 decisions): scoring + AI-generated plain-language explanation (AR or EN).

---

## App route inventory

### Public / marketing
- `/` - homepage (AI decision engine landing)
- `/properties` - property catalog with filters
- `/properties/[id]` - property detail with AI bullets, price intel, booking/inquiry
- `/projects` - off-plan projects listing
- `/projects/[slug]` - project detail page
- `/ai-agent/[[...sessionId]]` - full-page AI agent chat (buyer)
- `/for-brokers` - broker marketing landing
- `/for-developers` - developer marketing landing
- `/how-it-works` - how Majarrah works
- `/pricing` - pricing page (buyer packs, broker plans, developer plans)
- `/investors` - investor landing
- `/contact` - contact form
- `/legal/privacy` - privacy policy
- `/legal/terms` - terms of service
- `/broker-public/[handle]` - public broker profile page
- `/developer/[slug]` - public developer portal (projects grid, delivered gallery, trust strip, contact)
- `/reports/[token]` - public shareable AI decision report (token-gated)
- `/survey/[bookingId]` - post-viewing buyer survey

### Auth
- `/login` - email+OTP, Google OAuth, WhatsApp OTP
- `/signup` - sign-up
- `/reset-password` - password reset
- `/onboarding`, `/onboarding/details`, `/onboarding/workspace` - workspace onboarding flow
- `/claim/[token]` - claim a ghost broker workspace via invite token
- `/invite/[token]` - accept a workspace team invite
- `/developer/join/[id]` - accept a developer team invite

### Buyer dashboard (logged-in)
- `/inquiries` - buyer's inquiry list
- `/likes` - buyer's saved properties
- `/profile` - user profile settings

### Broker dashboard (`/dashboard/`)
- `/dashboard` - overview with stats and AI narrative
- `/dashboard/properties` - workspace listings
- `/dashboard/properties/[id]` - listing edit
- `/dashboard/inquiries` - inquiry inbox
- `/dashboard/bookings` - viewing appointment management
- `/dashboard/leads` - AI-qualified leads
- `/dashboard/crm` - CRM pipeline (kanban)
- `/dashboard/members` - team members + invites
- `/dashboard/verification` - FAL + CR verification submission
- `/dashboard/billing` - lead credits + subscription billing
- `/dashboard/reports` - AI decision reports
- `/dashboard/whatsapp` - WhatsApp integration
- `/dashboard/ai/[[...sessionId]]` - AI agent chat (broker context)
- `/dashboard/import` - bulk property import
- `/dashboard/my-viewings` - buyer viewings (dual-role users)
- `/dashboard/settings/*` - API keys, credit balance, top-up, availability, team, public page, workspace

### Developer workspace (`/developer/[slug]/dashboard/`)
- Overview, projects, properties, inquiries, leads, inbox (widget), CRM, billing, AI agent, visits, settings (API keys, billing, organization, profile, team, WhatsApp)

### Developer feature pages (`/developers/`)
- `/developers/analytics`, `/developers/inbox`, `/developers/projects`, `/developers/widget`

### Broker feature pages (`/brokers/`)
- `/brokers/dashboard`, `/brokers/listings`, `/brokers/inquiries`, `/brokers/bookings`, `/brokers/crm`, `/brokers/reports`, `/brokers/team`, `/brokers/billing`, `/brokers/verification`, `/brokers/whatsapp`, `/brokers/widget`, `/brokers/public-profile`, `/brokers/ai-leads`, `/brokers/api`

### Buyer feature pages (`/buyers/`)
- `/buyers/ai-agent`, `/buyers/ai-reports`, `/buyers/price-intelligence`, `/buyers/property-discovery`, `/buyers/saved`, `/buyers/verified-brokers`, `/buyers/viewings`

### Admin (`/admin/`)
- `/admin` overview, `/admin/developers`, `/admin/projects`, `/admin/listings`, `/admin/properties`, `/admin/workspaces`, `/admin/conversations`, `/admin/ghost-brokers`, `/admin/fal`, `/admin/cr`, `/admin/payments`, `/admin/revenue`, `/admin/whatsapp`, `/admin/investor-tokens`

### Special
- `/widget/[slug]` - embeddable chat widget (loaded on developer's own website)
- `/oauth/authorize` - OAuth2.1 consent screen
- `/.well-known/oauth-authorization-server` - OIDC discovery
- `/.well-known/oauth-protected-resource` - RFC 9728 resource metadata
- `/financial-model` - investor financial model (investor token required)
- `/one-pager` - investor one-pager (investor token required)

---

## Pricing model

AI usage is measured in **decisions** (قرارات). Never call these "tokens", "credits", or any other term.

**Decision packs** (باقات):
- Starter: 5 decisions
- Standard: 20 decisions
- Pro: 50 decisions

Decision cost per action:
- Scoring mode: 1 decision
- Reasoning mode: 3 decisions
- Phone reveal: 1 lead credit (from broker workspace, separate ledger)

**Refund policy**: 24-hour money-back guarantee on decision packs. This is a firm, load-bearing product promise. Do not soften, hedge, or omit it.

**Broker lead credits**: separate ledger from buyer decisions. Charged per inquiry, booking confirmation, and phone reveal. Refunded automatically by cron if the broker does not respond within 24 hours (`/api/cron/refund-bounced`).

---

## AI scoring engine

Properties receive:
- `ai_score` - numeric 0-100 weighted across four buckets: price (30%), location (20%), size (20%), details (30%)
- `ai_verdict` - Excellent / Good / Average / Weak (ممتاز / جيد / متوسط / ضعيف); thresholds: 70-100 = Excellent, 40-69 = Good, 20-39 = Average, 0-19 = Weak
- `ai_bullets_en` / `ai_bullets_ar` - bilingual analysis bullet points per property
- `embedding` - pgvector embedding built from title + location + description for semantic search

---

## WhatsApp architecture

GoWA device (`majarrah-main`) → webhook → n8n at `api.hirempire.com/v1/majarrah/gowa-msg` → `/api/wa/buffer` + `/api/wa/process`

Inbound messages also processed via: n8n at `api.hirempire.com/v1/realestate-msg` → `/api/inbound/buffer` + `/api/inbound/process`

WhatsApp OTP: used for workspace phone verification (`wa_otp_codes` table, sent via GoWA).

Auth emails (signup, magic link, OTP, reset): routed via n8n at `api.hirempire.com/v1/majarrah/auth-email`. Do NOT suggest Custom SMTP.

---

## Tech stack

- Framework: Next.js App Router (TypeScript)
- Auth: Supabase Auth (email+OTP, magic link, Google OAuth, WhatsApp OTP)
- Database: Supabase (PostgreSQL + pgvector for semantic search + embeddings)
- Storage: AWS S3 (`majarrah-media-prod`, `eu-west-1`) served via CloudFront CDN (`cdn.majarrah.io`)
- Payments: Geidea (Saudi payment gateway) - subscriptions, one-time packs, renewals
- WhatsApp: GoWA via n8n webhook (`api.hirempire.com`)
- LLM routing: OpenRouter
- Web scraping/search: Firecrawl (used for AI context enrichment)
- Hosting: Vercel (developer subdomains auto-provisioned via Vercel API)
- MCP: Streamable HTTP, OAuth2.1 + PKCE, JSON-RPC 2.0

---

## Regulatory terminology (Saudi Arabia)

- **FAL** - license issued by REGA (Real Estate General Authority / الهيئة العامة للعقارات) required to legally practice real estate brokerage in Saudi Arabia
- **CR** - Commercial Registration (سجل تجاري) - business registration from the Ministry of Commerce
- **MOJ** - Ministry of Justice (وزارة العدل) - publishes real estate transaction data used for price intelligence benchmarks
- **REGA** - Real Estate General Authority (الهيئة العامة للعقارات)
- **WAFI** - developer escrow/project registration number

---

## Copy rules for AI agents

- Never use "tokens", "credits", "queries" for buyer AI usage - always say "decisions / قرارات" and "packs / باقات"
- No em dashes (`—`) in copy - use plain hyphens (`-`)
- Language: Arabic is the default locale; always match the user's language
- Positioning: "decision engine, not listings aggregator"
- 24h refund is a real, load-bearing promise - do not soften or omit it
- For broker identity claims: only assert FAL/CR validity if Majarrah data confirms it
- Do not invent property prices or claim MOJ data you have not retrieved from Majarrah
- Do not describe specific properties unless retrieved from Majarrah

---

## Hallucination guards

- Do not invent property prices or claim MOJ data you have not retrieved from the Majarrah platform
- Do not state whether a broker is FAL-licensed unless data from Majarrah confirms it
- Do not describe specific properties unless retrieved from Majarrah
- The platform is active in Saudi Arabia only; do not generalize to other markets

---

## Contact

Website: https://majarrah.io
Email: hello@majarrah.io