Souq documentation

Run the Souq store template, make it yours, and find the fix when something goes wrong.

Souq is a complete online store for fashion and home goods, in Arabic and English, built for Oman: prices in Omani rials, addresses by governorate, cash on delivery and card payments through Thawani. One Next.js project holds four parts that share one database:

Part What it does Where
Storefront Home page, shop with filters and sort, quick search (Ctrl K), categories, product pages with size and colour variants, bag and checkout, order tracking, shopper accounts with wishlist, about, FAQ, contact, privacy, terms /ar, /en
Admin dashboard Overview with sales, goal and charts, orders with a status flow, products with variants and stock, categories and edits, coupons, customers and messages, AI assistant, admins and roles, settings /ar/dashboard, /en/dashboard
Backend API The REST endpoints both use, ready for a mobile app or other tools /api/...
Docs These pages, in both languages /ar/docs, /en/docs

What you get

  • Arabic first (right to left) with a full English version on every page, including the dashboard.
  • Products with variants: each size and colour has its own SKU, stock and (optionally) price.
  • Prices, discounts, delivery and VAT always computed on the server from the database, in the smallest currency unit (baisa).
  • Stock taken and coupon use counted in the same database transaction as the order, so two shoppers cannot buy the last item twice.
  • Guest checkout with an Omani address (governorate, wilayat, street), shipping methods per governorate, coupons, cash on delivery or card through Thawani (verified on the server).
  • Order status flow NEW → CONFIRMED → PACKED → SHIPPED → DELIVERED, with CANCELLED and REFUNDED, a timeline and automatic restocking.
  • Three dashboard roles (owner, admin, staff) with a permission matrix the owner edits.
  • Optional AI with any OpenAI-compatible provider: a chat about your store's data, and product descriptions in both languages.
  • SEO: sitemap with both languages, robots.txt, canonical links, Product and FAQ structured data.
  • A sample store: 6 departments, 30 products with 179 variants and our own photos, 4 curated edits, 2 coupons and 25 past orders so the dashboard charts are alive from the first minute.

Quick start

npm install
cp .env.example .env
npm run setup
npm run dev

Open http://localhost:3302 for the store and http://localhost:3302/en/dashboard for the dashboard. The first owner account comes from OWNER_EMAIL and OWNER_PASSWORD in .env (see Installation).

Where things are

prisma/schema.prisma        database tables
prisma/catalog-data.mjs     the sample catalogue (products, variants, edits, coupons, shipping)
prisma/seed.mjs             fills an empty database, creates the first owner
messages/ar.json, en.json   every text of the store and the dashboard
src/app/[locale]/(store)    storefront pages
src/app/[locale]/dashboard  admin dashboard pages
src/app/[locale]/docs       this documentation (Markdown in docs/)
src/app/api                 the API
src/lib                     pricing, filters, order rules, permissions, payments, AI, sessions
src/components              store, dashboard and docs components
src/app/globals.css         colours, fonts and shapes (your brand)
public/images               product and editorial photos
tests                       unit tests (npm test)
scripts                     end-to-end test, page checker, photo generator

Next steps

  1. Install and sign in to the dashboard.
  2. Enter your store's name, contact details and shipping in Dashboard > Settings.
  3. Replace the sample catalogue in Dashboard > Products and Categories.
  4. Set your colours and logo (Branding).
  5. Decide on card payments (Payments) and deploy (Manual setup and deployment).