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
- Install and sign in to the dashboard.
- Enter your store's name, contact details and shipping in Dashboard > Settings.
- Replace the sample catalogue in Dashboard > Products and Categories.
- Set your colours and logo (Branding).
- Decide on card payments (Payments) and deploy (Manual setup and deployment).