# SOUQ SHARE — Complete platform reference

This file is the long-form companion to /llms.txt. It exists so AI assistants
that follow the [/llms.txt convention](https://llmstxt.org) can grab a deep
overview of the platform without crawling every page.

## Mission

SOUQ SHARE is a bilingual (Arabic / English) global marketplace built to serve
the Arab world and any country with significant Arab/Muslim diaspora. It
combines three distinct products on one codebase:

1. **Classifieds marketplace** — country-bound listings (cars, real estate,
   electronics, fashion, etc.). Free with optional paid plans for unlimited /
   featured listings.
2. **Job board** — local job postings + a daily import of active vacancies from
   wazaayf.com (the operator's separate job-board product). Job seekers can
   post CVs as a "Job Seekers" subcategory under Jobs.
3. **Micro-services marketplace** — Fiverr/Khamsat-style global freelance
   services with platform-managed escrow, in-platform chat, file delivery,
   buyer acceptance, automatic accept after N days, dispute resolution, 1–5
   star reviews, and a per-user wallet.

The platform is publicly browsable; ordering services or posting requires an
account.

## Tech stack

- PHP 8.2 on Apache (cPanel)
- MariaDB / MySQL 8
- Frontend: vanilla HTML/CSS/JS + Font Awesome 6 + Chart.js (admin only)
- Payment gateways: Kashier (cards, Apple Pay), Vodafone Cash, InstaPay,
  bank transfer
- Email: SMTP via PHPMailer-like minimal client
- No build step; everything is server-rendered

## URL structure

| Path                                | Purpose                                      |
| ----------------------------------- | -------------------------------------------- |
| `/`                                 | Homepage                                     |
| `/browse.php`                       | Classifieds (with filters)                   |
| `/services.php`                     | Micro-services (with filters)                |
| `/ad.php?id=<id>`                   | Single ad detail                             |
| `/service.php?slug=<slug>`          | Single service detail                        |
| `/store.php?slug=<slug>`            | Merchant store                               |
| `/blog.php`                         | Blog index                                   |
| `/blog.php?slug=<slug>`             | Blog post                                    |
| `/pricing.php`                      | Plans & subscriptions                        |
| `/register.php`, `/login.php`       | Auth                                         |
| `/user/*`                           | Authenticated user area (requires login)     |
| `/admin/*`                          | Admin area (requires role=admin)             |
| `/sitemap.xml`                      | Sitemap                                      |
| `/llms.txt`, `/llms-full.txt`       | LLM-friendly summaries                       |
| `/robots.txt`                       | Crawler rules                                |
| `/ads.txt`                          | AdSense authorized sellers                   |

## Country subdomains (32 active)

Each subdomain auto-locks the visitor to that country's listings:

`sa.souqshare.com`, `eg.souqshare.com`, `ae.souqshare.com`, `kw.souqshare.com`,
`qa.souqshare.com`, `bh.souqshare.com`, `om.souqshare.com`, `jo.souqshare.com`,
`lb.souqshare.com`, `iq.souqshare.com`, `ma.souqshare.com`, `dz.souqshare.com`,
`tn.souqshare.com`, `ye.souqshare.com`, `sy.souqshare.com`, `ly.souqshare.com`,
`sd.souqshare.com`, `ps.souqshare.com`, `tr.souqshare.com`, `mr.souqshare.com`,
`de.souqshare.com`, `fr.souqshare.com`, `gb.souqshare.com`, `nl.souqshare.com`,
`be.souqshare.com`, `it.souqshare.com`, `es.souqshare.com`, `se.souqshare.com`,
`at.souqshare.com`, `ch.souqshare.com`, `us.souqshare.com`, `ca.souqshare.com`,
`au.souqshare.com`

Detection order in `currentCountry()`:
1. Subdomain ISO2 lookup (locked, immutable for the visitor)
2. GeoIP via ip-api.com (cached in session)
3. Default country from DB (`is_default = 1`)

## Language detection

Order in `Lang::detect()`:
1. `?lang=ar` or `?lang=en` URL parameter (persisted in session + cookie)
2. Saved session value
3. Cookie from previous visit
4. Country subdomain → AR if Arab country, else EN
5. Browser Accept-Language header (first tag)
6. Default: AR

Switching language never overrides the country lock — they are independent.

## Wallet & payment flows

### Top-up
1. User clicks "Top up wallet" on `/user/wallet.php`
2. `/user/wallet_topup.php` creates a `wallet_topups` row (status pending)
3. Redirect to `/pay.php?type=wallet_topup&id=<id>`
4. User pays via gateway → `Payments::markPaid()` runs
5. Amount is converted to wallet currency via `convertPrice()` and credited
   via `Wallet::credit(uid, amount, 'topup', ...)`
6. The `wallet_topups` row is marked `paid` with the credited amount.

### Withdraw
1. User submits `/user/wallet_withdraw.php` (method + account details)
2. `Wallet::requestWithdrawal()` immediately debits the balance and creates a
   `withdrawals` row (status pending)
3. Admin reviews in `/admin/withdrawals.php`. Approve → mark paid (offline
   transfer happens manually). Reject → funds refunded to wallet automatically.

### Service order escrow
1. Buyer pays via gateway or wallet → `service_orders.status = 'paid'`
2. Seller starts work → `'in_progress'`
3. Seller delivers (text + files) → `'delivered'`, `auto_accept_at = now+3d`
4. Buyer accepts → `Wallet::credit(seller, total − commission, 'order_earning', ...)`
   then `'completed'`
5. Buyer disputes → `'disputed'`, admin resolves by refund or release
6. Cancellation refunds full total to buyer wallet via `Wallet::credit(buyer, total, 'refund', ...)`

All wallet movements go through `Wallet::move()` which:
- Opens a DB transaction
- Locks the wallet row with `SELECT ... FOR UPDATE`
- Updates balance only if status='completed'
- Inserts an immutable row in `wallet_transactions` with `balance_after`

## Schema.org structured data

- Every page: `WebSite` + `Organization` (from `Seo::renderHead()`)
- Homepage: `CollectionPage` with `ItemList` of latest ads + `FAQPage` + `HowTo`
- Ad detail: `Product` with `Offer` (price, currency, availability)
- Service detail: `Service` with `Offer` and `Person` provider
- Blog post: `Article` with `Person` author
- Breadcrumbs: `BreadcrumbList` on browse, ad, service, blog detail

## Crawler etiquette

`robots.txt` whitelists every major AI crawler explicitly:
GPTBot, ClaudeBot, OAI-SearchBot, Google-Extended, PerplexityBot, Applebot,
Amazonbot, Meta-ExternalAgent, Bytespider, Diffbot, cohere-ai.

It disallows: `/admin/`, `/includes/`, `/install/`, `/lang/`, `/ajax/`,
`/user/`, `/logout.php`, `/report.php`, and pagination/sort query strings.

`Crawl-delay: 1` for general bots; Googlebot has no delay.

## Auto-cron jobs (daily)

- `cron/sync_wazaayf_jobs.php` — pulls active jobs from wazaayf.com API into
  `ads` (under the Jobs category) with `external_source='wazaayf_*'`
- `cron/sync_khedmah_services.php` — scrapes public service pages from
  khedmahonline.com and imports into `services` with
  `external_source='khedmahonline'`
- `cron/auto_accept_orders.php` — runs hourly, completes `delivered` service
  orders that hit `auto_accept_at`
- `cron/expire_stories.php` — purges expired store stories
- `cron/renew_warning.php` — sends "subscription expiring" emails
- `cron/email_digest.php` — daily/weekly digest of new listings

## Admin moderation surfaces

- `admin/ads.php` — approve/reject/feature classified listings
- `admin/services.php` — approve services (default status = pending)
- `admin/service_orders.php` — view all orders, resolve disputes
- `admin/withdrawals.php` — approve / mark paid / reject withdrawal requests
- `admin/blog.php` — approve blog posts
- `admin/reports.php` — review user reports
- `admin/analytics.php` — KPI charts, revenue trends, top categories/countries
- `admin/integrations.php` — manually trigger external syncs (wazaayf, khedmah)

## Contact

Operated by Mostafa Elwan Programming Co.
General: contact@souqshare.com