البنية التقنية للمطورين

مستودع واحد (Turborepo وpnpm لـTypeScript، وMelos لـFlutter)، وخادم NestJS واحد منظم كوحدة متكاملة مقسّمة إلى وحدات، وسبعة عملاء مولَّدة من عقد OpenAPI الخاص به.

الواجهة البرمجية والعامل الخلفي عمليتان مبنيتان من الكود نفسه وتتشاركان قاعدة PostgreSQL واحدة.

التقنيات

الطبقة	الاختيار
الخادم	NestJS 11، ‏Node 22+، ‏TypeScript صارم — وحدة متكاملة مقسّمة
قاعدة البيانات	PostgreSQL 16 مع Prisma؛ وSQL مباشر حيث لا يكفي Prisma (فهارس البحث، تجميعات دفتر الأستاذ)
البحث	Meilisearch خلف واجهة `SearchProvider` (ومحرك في الذاكرة للاختبارات)
التخزين	متوافق مع S3 ‏(MinIO محليًا، وSeaweedFS في الإنتاج) خلف واجهة `StorageProvider`؛ وimgproxy لتغيير أحجام الصور (غير منشور في الإنتاج بعد، فتُعرض الصور الأصلية)
الذاكرة المؤقتة / الطوابير	Redis 7 مهيأ؛ بلا طابور مهام — المهام الخلفية تستعلم قاعدة البيانات دوريًا
الدفع	واجهة `PaymentProvider`: الدفع عند الاستلام، Stripe، ‏Paymob (شكلي)، بطاقة تجريبية (للتطوير)
المصادقة	JWT للوصول (15 دقيقة) مع رموز تحديث متجددة، وصلاحيات حسب الدور، وتحقق ثنائي TOTP، ورموز لمرة واحدة بالبريد والرسائل، وGoogle وApple
الويب	Next.js 15 للمتجر؛ React وVite للوحات البائع والتوزيع والإدارة؛ Tailwind؛ TanStack Query
الجوال	Flutter مع Riverpod وgo_router وDio؛ وحزم مشتركة في `packages_dart/`
الاتصال الفوري	بوابة Socket.IO على `/realtime` لتتبع الطلبات وتحديثات الأسطول

الوحدات

توجد كل وحدة في apps/api/src/modules/<module>:

identity · customer · seller · catalog · search · media · inventory · pricing · promotion · cart · checkout · order · payment · ledger · shipping · delivery · realtime · engagement · content · platform · outbox · audit · privacy · cache

القواعد التي تحفظ صحة النظام

حدود الوحدات. لا تستورد وحدة مستودع بيانات وحدة أخرى أو كياناتها؛ بل تستدعي خدمتها العامة أو تتفاعل مع أحداثها. هذا يُبقي خيار فصل الخدمات لاحقًا.
صندوق الصادر. كل أثر جانبي (فهرسة البحث، الإشعارات، التحليلات، الـwebhooks، إنشاء مهام التوصيل) حدث يُكتب في معاملة التغيير نفسها، ثم ينقله العامل الخلفي.
منع التكرار. عمليات الكتابة على المال والطلبات تتطلب Idempotency-Key؛ وتُعاد الاستجابة المخزنة عند إعادة المحاولة.
دفتر أستاذ بقيد مزدوج. كل حدث مالي معاملة متوازنة؛ والأرصدة مشتقة وتُطابق كل ساعة.
حجوزات مخزون بمدة انتهاء. المتاح = الموجود ناقص المحجوز، ويُحسب تحت قفل صف؛ وتنتهي الحجوزات بدل الاعتماد على كتابة تعويضية.
آلات حالات صريحة للطلبات ومهام التوصيل والبائعين؛ لا شيء يكتب الحالة مباشرة.
عزل البائعين مفروض باختبار. كل استعلام على نموذج يملكه بائع يجب أن يُقيَّد بالمستدعي؛ واختبار يفحص الكود ويُفشل البناء عند أي استعلام غير مقيّد.
كتالوج الأخطاء. كل خطأ يحمل رمزًا من packages/contracts/src/errors.ts.
المال. أعداد صحيحة بالوحدة الصغرى مع رمز ISO؛ ونصوص في الشبكة؛ ونقاط أساس للنسب.
المعرّفات. UUID v7 تُولَّد في قاعدة البيانات.
الترحيلات للأمام فقط؛ والتغييرات بلا توقف تتبع أسلوب التوسيع ثم التقليص.

نموذج البيانات في خمسة قرارات

منتج ← متغيّر ← عرض: قائمة مشتركة، ووحدة بيع، وسعر بائع ومخزونه.
طلب ← مجموعات طلب: عملية شراء ودفعة واحدة، تنقسم لكل بائع للتنفيذ والتسوية.
دفتر أستاذ بقيد مزدوج: أرصدة البائعين وإيرادات المنصة ونقد السائقين مشتقة.
المخزون = الموجود − الحجوزات، مع مدة صلاحية للحجوزات.
كل أثر جانبي عبر صندوق الصادر.

يمتد المخطط على نحو 135 جدولًا في ملفات مثل identity وcatalog وorder وpayment وdelivery تحت apps/api/prisma/schema/. راجع docs/domain-model.md.

خريطة المستودع

apps/api            NestJS API + worker, Prisma schema and migrations
apps/storefront     Next.js buyer website
apps/seller-web     Seller console (React + Vite)
apps/delivery-web   Dispatch console (React + Vite)
apps/admin          Admin console (React + Vite)
apps/mobile/{buyer,seller,driver}   Flutter apps
packages/contracts  Error catalogue, Money, pagination, shared schemas
packages/sdk-ts     Generated TypeScript API client
packages_dart/      Shared Flutter packages (API client, UI, auth, l10n)
infra/              Docker Compose, Dockerfile, observability, Terraform notes
docs/               ADRs, domain model, endpoints, runbooks, this site

التشغيل محليًا

pnpm install
pnpm infra:up                         # Postgres, Redis, Meilisearch, MinIO, Mailpit, imgproxy
pnpm --filter @mp/api prisma:migrate
pnpm --filter @mp/api seed
pnpm --filter @mp/api dev             # API + worker
pnpm --filter @mp/storefront dev      # and any other surface

تستمع الواجهة البرمجية على المنفذ 3001 مع Swagger على /docs. بوابات الجودة: pnpm lint && pnpm typecheck && pnpm test؛ ولـFlutter: ‏melos run analyze وmelos run test.