المبيعات والانتشار

التمويل والشراكات

البنية المعمارية

نمط مرآة قائم على الميزات، متعدد المستأجرين افتراضياً، آمن النوع end-to-end. Serverless على Vercel + Neon.

المبادئ

مدفوعة بالمكونات — Radix primitives في القاع، shadcn/ui atoms فوقها، feature blocks في القمة.
قائمة على الميزات — كل ميزة مجلد قائم بذاته، والمسارات تعكس المكونات 1:1.
Serverless-first — Vercel + Neon Postgres، بيئة Edge حيث لا يحتاج Prisma.
آمن النوع end-to-end — Prisma → Zod → TypeScript بلا تسليمات يدوية.
Async-first — PRs صغيرة، قرارات موثّقة، تقدّم ثابت.

طبقات التركيب

الأساس: Radix UI → shadcn/ui → نظام shadcn.
اللبنات: UI → atoms → templates → blocks → micros → apps.

نمط المرآة

كل مسار URL ينتج مجلدين — أحدهما في app/ للتوجيه واللوايآت، وآخر في components/ لكل منطق الميزة. التطابق 1:1 يعني: إن عرفت الـURL عرفت مكان الكود.

للمسار /abc:

app/[lang]/abc/ — page.tsx, layout.tsx
components/abc/ — content.tsx, actions.ts, form.tsx, validation.ts, types.ts, use-abc.ts, README.md

src/— Source code directory

app/— Next.js App Router (Routing & Layouts)

[lang]/— i18n support

abc/— URL route: /abc

page.tsx— Route entry point

layout.tsx— Route layout

components/— Component Logic (Mirrors app structure)

abc/— Mirrors app/[lang]/abc/

content.tsx— Page UI: headings, sections, layout

actions.ts— Server actions: validate, mutate

config.ts— Enums, option lists, defaults

validation.ts— Zod schemas & refinements

types.ts— Domain and UI types

form.tsx— Typed forms (RHF)

card.tsx— KPIs, summaries, quick actions

all.tsx— List view with table, filters

detail.tsx— Detail view with sections

column.tsx— Table column builders

use-abc.ts— Feature hooks

README.md— Feature purpose, APIs, decisions

ISSUE.md— Known issues and follow-ups

atom/— Atomic UI components

template/— Reusable layout templates

ui/— Base UI components (shadcn/ui)

الحزمة التقنية

الإطار: Next.js 16.2.x مع App Router وTurbopack، React 19.2.x، TypeScript 5.x
قاعدة البيانات: PostgreSQL مع Prisma ORM 6.19.x (302 نموذج، 149 enum، 73 ملف schema)، Neon Serverless
المصادقة: NextAuth v5 (beta.30) مع Prisma adapter متعدد المستأجرين مخصّص
التنسيق: Tailwind CSS v4 مع تنسيق ألوان OKLCH
مكونات UI: Radix UI primitives + shadcn/ui (35 مجلد مكوّن)
التحقق: Zod 4.0.14 مع React Hook Form 7.61.1
التدويل: عربية (RTL) + إنجليزية (LTR) مع ترجمة عند الطلب
الوثائق: MDX مع Fumadocs
استراتيجية Runtime: Node.js للصفحات التي تحتاج Prisma/bcrypt، Edge للوسيط/الثابت
التخزين: AWS S3 + CloudFront CDN للصور، Upstash Redis للنطاقات المخصصة

الأنماط المعيارية للملفات

كل مجلد ميزة يتّبع هذه التسميات:

الملف	الغرض
`content.tsx`	مكوّن خادم: جلب البيانات، تكوين، تنظيم تخطيط
`client.tsx`	حدود العميل: غلاف `"use client"` واحد لكل ميزة (جديد)
`actions.ts`	server actions وAPI calls: تحقق، تحديد نطاق المستأجر، تعديل
`queries.ts`	استعلامات قراءة فقط: select objects، where-builders، pagination، إحصاءات
`authorization.ts`	فحوص صلاحيات RBAC: check/assert/can/getAllowedActions لكل ميزة
`config.ts`	enums، قوائم خيارات، تسميات، افتراضيات
`validation.ts`	Zod schemas وrefinements، parse وinfer للأنواع
`types.ts`	أنواع المجال والـUI، helpers عامة للنماذج/الجداول
`form.tsx`	نماذج RHF بمحلّلات وتعامل إرسال
`card.tsx`	بطاقات لـKPIs والملخصات والإجراءات السريعة
`all.tsx`	عرض القائمة مع جدول ومرشّحات وpagination
`featured.tsx`	قائمة ميزات منتقاة
`detail.tsx`	عرض التفاصيل بأقسام وعلاقات وإجراءات
`util.ts`	utilities خالصة وmappers
`columns.tsx`	بُناة أعمدة Table مكتوبة وعارضات خلايا
`use-abc.ts`	hooks الميزة: جلب، تعديل، حالة مشتقّة
`table.tsx`	مكوّن عميل يلفّ atom DataTable مع أعمدة وtoolbar وmodals
`list-params.ts`	URL search-param cache عبر nuqs لحالة جدول آمنة النوع
`README.md`	سياق الميزة: جداول مرجعية، ملفات، قرارات، نقاط دخول (~40 سطر)
`ISSUE.md`	issues نشطة، سجل منجَز، متابعة الديون التقنية (~40 سطر)

إطار القرار

نمط المرآة أولاً: كل مسار جديد في app/[lang]/ يجب أن يكون له مجلد مرآة في components/
إعادة استخدام المكون: ابدأ بمكونات shadcn/ui ولا توسّع إلا عند الضرورة
التزام نمط الملفات: استخدم الأسماء المعيارية (content.tsx، action.ts، …)
سلسلة آمن النوع: Zod schemas → TypeScript types → Prisma models
توافق Serverless: افتراضي Edge runtime ما لم يُطلب Prisma/bcrypt
عزل الميزة: كل ميزة قابلة للنشر والاختبار بشكل مستقل
تقدّم تدريجي: UI → Atoms → Templates → Blocks → Micro → Apps
تجربة المطوّر: بنية متوقّعة، أسماء واضحة، قرارات موثّقة

أعراف التسمية

المكونات: kebab-case للملفات (button.tsx, user-profile.tsx)
الصفحات: kebab-case لمقاطع المسار (user-profile, sign-in)
Hooks: بادئة use- (use-leads.ts, use-upwork.ts)
الأنواع: PascalCase للواجهات والأنواع
الثوابت: UPPER_SNAKE_CASE أو camelCase للكائنات

ملفات حرجة

الملف	الأسطر	الغرض
`src/proxy.ts`	388	Edge middleware: استخراج النطاق، RBAC، إعادة كتابة، نطاقات مخصصة
`src/auth.ts`	777	NextAuth: JWT callbacks، إدارة الجلسات، منطق إعادة التوجيه
`src/auth.config.ts`	151	مزوّدو OAuth: Google، Facebook، Credentials
`src/routes.ts`	410	مصفوفة RBAC: حماية المسارات حسب الدور
`src/lib/rate-limit.ts`	537	تحديد المعدل: 14 إعداداً عبر المسارات
`src/lib/tenant-context.ts`	189	حلّ المستأجر مع caching
`src/components/catalog/setup.ts`	1,717	جسر الكتالوج: تزويد بنية أكاديمية
`src/lib/dns-service.ts`	644	تحقّق DNS: مزوّدون متعدّدون للنطاقات المخصّصة
`src/lib/security-headers.ts`	173	CSP، HSTS، حماية XSS
`prisma/models/`	73 ملف	302 نموذج، 149 enum
`CLAUDE.md`	—	إرشادات معمارية على مستوى المشروع

مضادات الأنماط

مكونات لا تتبع بنية نمط المرآة.
مكونات أحادية ضخمة كان يجب تفكيكها.
غياب سلسلة آمن النوع (Zod → TypeScript → Prisma).
ملفات لا تتّبع تسميات معيارية.
اقتران محكم بين الميزات.
قيم مكتوبة في الكود يجب أن تعيش في config.ts.
استعلامات قاعدة بيانات مباشرة خارج actions.ts / queries.ts.

دورة حياة الطلب

المستخدم يتفاعل مع form.tsx، الإرسال يطلق server action من actions.ts.
الحمولة تُتحقّق منها بـ Zod schema في validation.ts.
الـaction يستدعي queries.ts أو actions.ts، اللذين يستخدمان Prisma على Neon مع الأنواع من types.ts.
النتيجة تتدفّق عودة، وhook من use-abc.ts يحدّث الواجهة.

البيئة المحلية الهيكل

On This Page

المبادئ طبقات التركيب نمط المرآة الحزمة التقنية الأنماط المعيارية للملفات إطار القرار أعراف التسمية ملفات حرجة مضادات الأنماط دورة حياة الطلب

المبيعات والانتشار

التمويل والشراكات

البنية المعمارية

نمط مرآة قائم على الميزات، متعدد المستأجرين افتراضياً، آمن النوع end-to-end. Serverless على Vercel + Neon.

المبادئ

مدفوعة بالمكونات — Radix primitives في القاع، shadcn/ui atoms فوقها، feature blocks في القمة.
قائمة على الميزات — كل ميزة مجلد قائم بذاته، والمسارات تعكس المكونات 1:1.
Serverless-first — Vercel + Neon Postgres، بيئة Edge حيث لا يحتاج Prisma.
آمن النوع end-to-end — Prisma → Zod → TypeScript بلا تسليمات يدوية.
Async-first — PRs صغيرة، قرارات موثّقة، تقدّم ثابت.

طبقات التركيب

الأساس: Radix UI → shadcn/ui → نظام shadcn.
اللبنات: UI → atoms → templates → blocks → micros → apps.

نمط المرآة

للمسار /abc:

app/[lang]/abc/ — page.tsx, layout.tsx
components/abc/ — content.tsx, actions.ts, form.tsx, validation.ts, types.ts, use-abc.ts, README.md

src/— Source code directory

app/— Next.js App Router (Routing & Layouts)

[lang]/— i18n support

abc/— URL route: /abc

page.tsx— Route entry point

layout.tsx— Route layout

components/— Component Logic (Mirrors app structure)

abc/— Mirrors app/[lang]/abc/

content.tsx— Page UI: headings, sections, layout

actions.ts— Server actions: validate, mutate

config.ts— Enums, option lists, defaults

validation.ts— Zod schemas & refinements

types.ts— Domain and UI types

form.tsx— Typed forms (RHF)

card.tsx— KPIs, summaries, quick actions

all.tsx— List view with table, filters

detail.tsx— Detail view with sections

column.tsx— Table column builders

use-abc.ts— Feature hooks

README.md— Feature purpose, APIs, decisions

ISSUE.md— Known issues and follow-ups

atom/— Atomic UI components

template/— Reusable layout templates

ui/— Base UI components (shadcn/ui)

الحزمة التقنية

الإطار: Next.js 16.2.x مع App Router وTurbopack، React 19.2.x، TypeScript 5.x
قاعدة البيانات: PostgreSQL مع Prisma ORM 6.19.x (302 نموذج، 149 enum، 73 ملف schema)، Neon Serverless
المصادقة: NextAuth v5 (beta.30) مع Prisma adapter متعدد المستأجرين مخصّص
التنسيق: Tailwind CSS v4 مع تنسيق ألوان OKLCH
مكونات UI: Radix UI primitives + shadcn/ui (35 مجلد مكوّن)
التحقق: Zod 4.0.14 مع React Hook Form 7.61.1
التدويل: عربية (RTL) + إنجليزية (LTR) مع ترجمة عند الطلب
الوثائق: MDX مع Fumadocs
استراتيجية Runtime: Node.js للصفحات التي تحتاج Prisma/bcrypt، Edge للوسيط/الثابت
التخزين: AWS S3 + CloudFront CDN للصور، Upstash Redis للنطاقات المخصصة

الأنماط المعيارية للملفات

كل مجلد ميزة يتّبع هذه التسميات:

الملف	الغرض
`content.tsx`	مكوّن خادم: جلب البيانات، تكوين، تنظيم تخطيط
`client.tsx`	حدود العميل: غلاف `"use client"` واحد لكل ميزة (جديد)
`actions.ts`	server actions وAPI calls: تحقق، تحديد نطاق المستأجر، تعديل
`queries.ts`	استعلامات قراءة فقط: select objects، where-builders، pagination، إحصاءات
`authorization.ts`	فحوص صلاحيات RBAC: check/assert/can/getAllowedActions لكل ميزة
`config.ts`	enums، قوائم خيارات، تسميات، افتراضيات
`validation.ts`	Zod schemas وrefinements، parse وinfer للأنواع
`types.ts`	أنواع المجال والـUI، helpers عامة للنماذج/الجداول
`form.tsx`	نماذج RHF بمحلّلات وتعامل إرسال
`card.tsx`	بطاقات لـKPIs والملخصات والإجراءات السريعة
`all.tsx`	عرض القائمة مع جدول ومرشّحات وpagination
`featured.tsx`	قائمة ميزات منتقاة
`detail.tsx`	عرض التفاصيل بأقسام وعلاقات وإجراءات
`util.ts`	utilities خالصة وmappers
`columns.tsx`	بُناة أعمدة Table مكتوبة وعارضات خلايا
`use-abc.ts`	hooks الميزة: جلب، تعديل، حالة مشتقّة
`table.tsx`	مكوّن عميل يلفّ atom DataTable مع أعمدة وtoolbar وmodals
`list-params.ts`	URL search-param cache عبر nuqs لحالة جدول آمنة النوع
`README.md`	سياق الميزة: جداول مرجعية، ملفات، قرارات، نقاط دخول (~40 سطر)
`ISSUE.md`	issues نشطة، سجل منجَز، متابعة الديون التقنية (~40 سطر)

إطار القرار

نمط المرآة أولاً: كل مسار جديد في app/[lang]/ يجب أن يكون له مجلد مرآة في components/
إعادة استخدام المكون: ابدأ بمكونات shadcn/ui ولا توسّع إلا عند الضرورة
التزام نمط الملفات: استخدم الأسماء المعيارية (content.tsx، action.ts، …)
سلسلة آمن النوع: Zod schemas → TypeScript types → Prisma models
توافق Serverless: افتراضي Edge runtime ما لم يُطلب Prisma/bcrypt
عزل الميزة: كل ميزة قابلة للنشر والاختبار بشكل مستقل
تقدّم تدريجي: UI → Atoms → Templates → Blocks → Micro → Apps
تجربة المطوّر: بنية متوقّعة، أسماء واضحة، قرارات موثّقة

أعراف التسمية

المكونات: kebab-case للملفات (button.tsx, user-profile.tsx)
الصفحات: kebab-case لمقاطع المسار (user-profile, sign-in)
Hooks: بادئة use- (use-leads.ts, use-upwork.ts)
الأنواع: PascalCase للواجهات والأنواع
الثوابت: UPPER_SNAKE_CASE أو camelCase للكائنات

ملفات حرجة

الملف	الأسطر	الغرض
`src/proxy.ts`	388	Edge middleware: استخراج النطاق، RBAC، إعادة كتابة، نطاقات مخصصة
`src/auth.ts`	777	NextAuth: JWT callbacks، إدارة الجلسات، منطق إعادة التوجيه
`src/auth.config.ts`	151	مزوّدو OAuth: Google، Facebook، Credentials
`src/routes.ts`	410	مصفوفة RBAC: حماية المسارات حسب الدور
`src/lib/rate-limit.ts`	537	تحديد المعدل: 14 إعداداً عبر المسارات
`src/lib/tenant-context.ts`	189	حلّ المستأجر مع caching
`src/components/catalog/setup.ts`	1,717	جسر الكتالوج: تزويد بنية أكاديمية
`src/lib/dns-service.ts`	644	تحقّق DNS: مزوّدون متعدّدون للنطاقات المخصّصة
`src/lib/security-headers.ts`	173	CSP، HSTS، حماية XSS
`prisma/models/`	73 ملف	302 نموذج، 149 enum
`CLAUDE.md`	—	إرشادات معمارية على مستوى المشروع

مضادات الأنماط

مكونات لا تتبع بنية نمط المرآة.
مكونات أحادية ضخمة كان يجب تفكيكها.
غياب سلسلة آمن النوع (Zod → TypeScript → Prisma).
ملفات لا تتّبع تسميات معيارية.
اقتران محكم بين الميزات.
قيم مكتوبة في الكود يجب أن تعيش في config.ts.
استعلامات قاعدة بيانات مباشرة خارج actions.ts / queries.ts.

دورة حياة الطلب

المستخدم يتفاعل مع form.tsx، الإرسال يطلق server action من actions.ts.
الحمولة تُتحقّق منها بـ Zod schema في validation.ts.
الـaction يستدعي queries.ts أو actions.ts، اللذين يستخدمان Prisma على Neon مع الأنواع من types.ts.
النتيجة تتدفّق عودة، وhook من use-abc.ts يحدّث الواجهة.

البيئة المحلية الهيكل

On This Page

بالقلم

البنية المعمارية

المبادئ

طبقات التركيب

نمط المرآة

الحزمة التقنية

الأنماط المعيارية للملفات

إطار القرار

أعراف التسمية

ملفات حرجة

مضادات الأنماط

دورة حياة الطلب

بالقلم

البنية المعمارية

المبادئ

طبقات التركيب

نمط المرآة

الحزمة التقنية

الأنماط المعيارية للملفات

إطار القرار

أعراف التسمية

ملفات حرجة

مضادات الأنماط

دورة حياة الطلب