diyaa.de/docs/STACK.md

🧱 الستاك الموصى به — diyaa.de

القرار: Next.js فل ستاك + PostgreSQL + Prisma. كل شي بمشروع واحد، مكوّنات قابلة لإعادة الاستخدام، ومكتبات محليّة (self-hosted) قدر الإمكان.

تحديث 2026-08-05: المخطط اعتُمد على الخيار A — جدول Project موحّد + Melody منفصل (تفاصيله بـ ARCHITECTURE.md §3). الاحصائيات: عدّادات داخلية أولاً بدل Umami. راجع قرارات المراجعة بـ REVIEW-2026-08-05.md.

---

الخلاصة السريعة

الطبقة	الاختيار	ليش
Framework	Next.js 14 (App Router) — موجود	فرونت + باك اند بمشروع واحد، Server Actions & Route Handlers
اللغة	TypeScript (strict) — موجود	أمان أنواع، أسهل للـ agents يفهموا الكود
التنسيق	Tailwind CSS	معيار مطلوب، utility-first، متناسق
مكوّنات UI	shadcn/ui (Radix + Tailwind)	مكوّنات محليّة (بتتنسخ للريبو مش package)، قابلة للتعديل الكامل
قاعدة البيانات	PostgreSQL	علاقات قوية (أعمال ↔ تصنيفات ↔ ألحان)، ممتاز محلياً وعلى السيرفر
ORM	Prisma	Schema واحد = مصدر الحقيقة، migrations منظّمة، type-safe
المصادقة (Admin)	Auth.js (NextAuth v5) بـ Credentials	لوحة تحكم لك وحدك، بدون طرف ثالث
رفع الملفات	تخزين محلي على الـ VPS (volume) + معالجة بـ sharp	صور الأعمال والسكرين شوتس والصوت — self-hosted، بدون S3 إلزامي
الصوت (الألحان)	<audio> عنصر أصلي + مشغّل مخصّص (wavesurfer.js اختياري، محلي)	تشغيل الألحان بدون خدمة خارجية
الإيميلات	Nodemailer + SMTP (STRATO أو أي مزوّد)	تحكّم كامل، بدون API طرف ثالث
قوالب الإيميل	React Email	قوالب بمكوّنات React، متسقة مع باقي الستاك
الاحصائيات	عدّادات داخلية بسيطة أولاً (Umami self-hosted لاحقاً لو لزم)	أخف، خصوصية أعلى، بدون خدمة إضافية للإطلاق الأول
الفاليديشن	Zod	تحقّق من الفورمات والـ API، متكامل مع Prisma/TS
الفورمات	React Hook Form + Zod	إدارة نماذج لوحة التحكم
النشر	Docker + Traefik + Makefile — موجود	نفس المنظومة الحالية، بنضيف عليها Postgres

---

ليش Next.js فل ستاك (مش باك اند منفصل)؟

• مشروع واحد = صيانة أسهل وتوثيق أوضح للـ agents.
• Server Actions بتلغي الحاجة لطبقة API منفصلة لمعظم عمليات لوحة التحكم.
• Route Handlers (app/api/...) لأي endpoints عامة (مثلاً webhook، رفع، RSS للألحان).
• كل شي TypeScript من الداتابيس للواجهة = نوع واحد يمشي من Prisma لـ React.

ليش PostgreSQL + Prisma؟

• بياناتك علائقية: عمل واحد ينتمي لتصنيف، تطبيق إله كذا سكرين شوت، لحن إله تصنيف (عربي/شرقي). Postgres مثالي لهيك.
• Prisma بيخلّي schema.prisma مصدر الحقيقة الوحيد للبنية — وهاد بيخدم شرط التوثيق.
• migrations منظّمة → تشتغل نفسها محلياً وعلى السيرفر.

مبدأ "كل المكتبات محليّة"

• shadcn/ui: بتتنسخ داخل components/ui/ — مش dependency خارجي، تحت سيطرتك بالكامل.
• الخطوط: self-hosted عبر next/font (بدون Google Fonts CDN).
• الأيقونات: lucide-react (bundled محلياً).
• مشغّل الصوت والاحصائيات: self-hosted على نفس الـ VPS.
• تجنّب أي CDN وقت التشغيل — كل شي يتحزّم مع الـ build.

---

حزم مقترحة للتثبيت (مرجع)

# UI
tailwindcss postcss autoprefixer
# shadcn/ui يُهيّأ عبر: npx shadcn@latest init
class-variance-authority clsx tailwind-merge lucide-react tailwindcss-animate
# DB
prisma @prisma/client
# Auth
next-auth@beta
# Forms & validation
react-hook-form zod @hookform/resolvers
# Email
nodemailer @react-email/components @react-email/render
# Media
sharp
# (اختياري) مشغّل صوت
wavesurfer.js

⚠️ لا تثبّت شي إلا وقت الحاجة الفعلية للـ feature المرتبط فيه، وحدّث PROJECT-STATE.md بعد كل إضافة.