الهندسة المعمارية

مهندسة لإعادة الاستخدام والمجتمع، تستخدم نمطاً موحداً قائماً على الميزات، مع الحفاظ على كل مكون مستقلاً وقابلاً للاكتشاف.

من radix، shadcn، atoms، templates، blocks، micros — إلى تحفة كاملة.

هندستنا المعمارية مصممة من الصفر لإعادة الاستخدام والنمطية وتجربة مطور عالمية المستوى. إنها ليست مجرد نظام لبناء التطبيقات؛ إنها إطار لتكوين مكونات أتمتة "ذرية" في نظام بيئي قوي وتعاوني ومعزز بالذكاء الاصطناعي.

مبادئ الهندسة المعمارية الأساسية

النمطية المدفوعة بالمكونات – مستوحاة من فلسفة shadcn/ui، توفر مكونات قابلة لإعادة الاستخدام والتخصيص في حالتها الأساسية والأدنى
تجربة مطور متفوقة – هيكل بديهي ومتوقع للإنتاجية
قائم على الميزات وقابل للتكوين – نهج الخدمات المصغرة والواجهات الأمامية المصغرة مع مكونات مستقلة
السحابة أولاً – النشر على Vercel مع Neon Postgres لقاعدة بيانات سحابية
أمان النوع افتراضياً – Prisma + Zod + TypeScript عبر المجموعة
غير متزامن أولاً – طلبات سحب صغيرة، قرارات موثقة، تقدم ثابت

التسلسل الهرمي للتكوين

طبقة الأساس: Radix UI → shadcn/ui → نظام shadcn البيئي
اللبنات الأساسية: UI → Atoms → Templates → Blocks → Micro → 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، ISSUE.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.0.3 مع App Router وTurbopack، React 19.2.0، TypeScript
قاعدة البيانات: PostgreSQL مع Prisma ORM 6.16.2، Neon للسحابة
المصادقة: NextAuth v5 (beta) مع محول Prisma، OAuth وبيانات الاعتماد
التنسيق: Tailwind CSS v4 مع تنسيق ألوان OKLCH، نظام تصميم مخصص
مكونات UI: بدائيات Radix UI + مكونات shadcn/ui مخصصة
التدويل: i18n مخصص مع دعم الإنجليزية/العربية (RTL)
التوثيق: MDX مع مكونات مخصصة
استراتيجية وقت التشغيل: وقت تشغيل Node.js لصفحات Prisma/bcrypt، وقت تشغيل Edge للأخرى
أمان النوع: TypeScript Generics تُستخدم بكثافة لإعادة الاستخدام

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

كل دليل ميزة يتبع اصطلاحات التسمية هذه:

الملف	الغرض
`content.tsx`	تكوين واجهة الميزة/الصفحة: العناوين، الأقسام، تنسيق التخطيط
`actions.ts`	إجراءات الخادم واستدعاءات API: التحقق، نطاق المستأجر، التغيير
`config.ts`	التعدادات، قوائم الخيارات، التسميات، الافتراضيات للميزة
`validation.ts`	مخططات Zod والتحسينات؛ التحليل واستنتاج الأنواع
`types.ts`	أنواع المجال والواجهة؛ مساعدات عامة للنماذج/الجداول
`form.tsx`	نماذج مكتوبة (RHF) مع المحللين ومعالجة الإرسال
`card.tsx`	مكونات البطاقات لمؤشرات الأداء الرئيسية، الملخصات، الإجراءات السريعة
`all.tsx`	عرض القائمة مع الجدول، المرشحات، التصفح
`featured.tsx`	قائمة ميزات منتقاة تعرض الاختيارات
`detail.tsx`	عرض التفاصيل مع الأقسام، العلاقات، الإجراءات
`util.ts`	أدوات نقية ومحولات تُستخدم في الميزة
`column.tsx`	بناة أعمدة الجدول المكتوبة وعارضي الخلايا
`use-abc.ts`	خطافات الميزة: الجلب، التغييرات، الحالة المشتقة
`README.md`	README الميزة: الغرض، APIs، القرارات
`ISSUE.md`	المشكلات المعروفة والمتابعات للميزة

إطار القرار

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

اصطلاحات التسمية

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

مرجع الملفات الحرجة

الملف	الغرض
`src/auth.ts`	تكوين NextAuth
`src/middleware.ts`	توجيه Auth وi18n
`src/routes.ts`	تعريفات المسارات العامة/الخاصة
`prisma/schema.prisma`	مخطط قاعدة البيانات
`src/app/globals.css`	متغيرات السمة
`src/components/ui/`	مكونات shadcn/ui الأساسية
`src/components/atom/`	مكونات التصميم الذري
`src/components/template/`	قوالب التخطيط (header، sidebar)
`CLAUDE.md`	إرشادات الهندسة المعمارية على مستوى المشروع

كشف الأنماط المضادة

احترس من هذه الأخطاء الشائعة:

مكونات لا تتبع هيكل نمط المرآة
مكونات متجانسة يجب تفكيكها
سلسلة أمان نوع مفقودة (تحققات Zod، أنواع TypeScript)
ملفات لا تتبع اصطلاحات التسمية المعيارية
ميزات مع اقتران محكم يمنع النشر المستقل
قيم مشفرة بدلاً من استخدام config.ts
استعلامات قاعدة بيانات مباشرة بدلاً من استخدام أنماط actions.ts

تفاعل نموذجي

يتفاعل مستخدم مع مكون من form.tsx على واجهة Next.js الأمامية، مما يُفعّل إجراء خادم من actions.ts
يتم التحقق من حمولة الطلب بواسطة مخطط Zod من validation.ts
تستخدم الوظيفة السحابية عميل Prisma الآمن للاستعلام عن Neon، باستخدام واجهات من types.ts
يتم بث النتيجة وإدارتها بواسطة خطاف من use-abc.ts، مما يحدث الواجهة بكفاءة

البدء الهيكل

On This Page

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

الهندسة المعمارية

من radix، shadcn، atoms، templates، blocks، micros — إلى تحفة كاملة.

مبادئ الهندسة المعمارية الأساسية

النمطية المدفوعة بالمكونات – مستوحاة من فلسفة shadcn/ui، توفر مكونات قابلة لإعادة الاستخدام والتخصيص في حالتها الأساسية والأدنى
تجربة مطور متفوقة – هيكل بديهي ومتوقع للإنتاجية
قائم على الميزات وقابل للتكوين – نهج الخدمات المصغرة والواجهات الأمامية المصغرة مع مكونات مستقلة
السحابة أولاً – النشر على Vercel مع Neon Postgres لقاعدة بيانات سحابية
أمان النوع افتراضياً – Prisma + Zod + TypeScript عبر المجموعة
غير متزامن أولاً – طلبات سحب صغيرة، قرارات موثقة، تقدم ثابت

التسلسل الهرمي للتكوين

طبقة الأساس: Radix UI → shadcn/ui → نظام shadcn البيئي
اللبنات الأساسية: UI → Atoms → Templates → Blocks → Micro → 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، ISSUE.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.0.3 مع App Router وTurbopack، React 19.2.0، TypeScript
قاعدة البيانات: PostgreSQL مع Prisma ORM 6.16.2، Neon للسحابة
المصادقة: NextAuth v5 (beta) مع محول Prisma، OAuth وبيانات الاعتماد
التنسيق: Tailwind CSS v4 مع تنسيق ألوان OKLCH، نظام تصميم مخصص
مكونات UI: بدائيات Radix UI + مكونات shadcn/ui مخصصة
التدويل: i18n مخصص مع دعم الإنجليزية/العربية (RTL)
التوثيق: MDX مع مكونات مخصصة
استراتيجية وقت التشغيل: وقت تشغيل Node.js لصفحات Prisma/bcrypt، وقت تشغيل Edge للأخرى
أمان النوع: TypeScript Generics تُستخدم بكثافة لإعادة الاستخدام

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

كل دليل ميزة يتبع اصطلاحات التسمية هذه:

الملف	الغرض
`content.tsx`	تكوين واجهة الميزة/الصفحة: العناوين، الأقسام، تنسيق التخطيط
`actions.ts`	إجراءات الخادم واستدعاءات API: التحقق، نطاق المستأجر، التغيير
`config.ts`	التعدادات، قوائم الخيارات، التسميات، الافتراضيات للميزة
`validation.ts`	مخططات Zod والتحسينات؛ التحليل واستنتاج الأنواع
`types.ts`	أنواع المجال والواجهة؛ مساعدات عامة للنماذج/الجداول
`form.tsx`	نماذج مكتوبة (RHF) مع المحللين ومعالجة الإرسال
`card.tsx`	مكونات البطاقات لمؤشرات الأداء الرئيسية، الملخصات، الإجراءات السريعة
`all.tsx`	عرض القائمة مع الجدول، المرشحات، التصفح
`featured.tsx`	قائمة ميزات منتقاة تعرض الاختيارات
`detail.tsx`	عرض التفاصيل مع الأقسام، العلاقات، الإجراءات
`util.ts`	أدوات نقية ومحولات تُستخدم في الميزة
`column.tsx`	بناة أعمدة الجدول المكتوبة وعارضي الخلايا
`use-abc.ts`	خطافات الميزة: الجلب، التغييرات، الحالة المشتقة
`README.md`	README الميزة: الغرض، APIs، القرارات
`ISSUE.md`	المشكلات المعروفة والمتابعات للميزة

إطار القرار

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

اصطلاحات التسمية

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

مرجع الملفات الحرجة

الملف	الغرض
`src/auth.ts`	تكوين NextAuth
`src/middleware.ts`	توجيه Auth وi18n
`src/routes.ts`	تعريفات المسارات العامة/الخاصة
`prisma/schema.prisma`	مخطط قاعدة البيانات
`src/app/globals.css`	متغيرات السمة
`src/components/ui/`	مكونات shadcn/ui الأساسية
`src/components/atom/`	مكونات التصميم الذري
`src/components/template/`	قوالب التخطيط (header، sidebar)
`CLAUDE.md`	إرشادات الهندسة المعمارية على مستوى المشروع

كشف الأنماط المضادة

احترس من هذه الأخطاء الشائعة:

مكونات لا تتبع هيكل نمط المرآة
مكونات متجانسة يجب تفكيكها
سلسلة أمان نوع مفقودة (تحققات Zod، أنواع TypeScript)
ملفات لا تتبع اصطلاحات التسمية المعيارية
ميزات مع اقتران محكم يمنع النشر المستقل
قيم مشفرة بدلاً من استخدام config.ts
استعلامات قاعدة بيانات مباشرة بدلاً من استخدام أنماط actions.ts

تفاعل نموذجي

يتفاعل مستخدم مع مكون من form.tsx على واجهة Next.js الأمامية، مما يُفعّل إجراء خادم من actions.ts
يتم التحقق من حمولة الطلب بواسطة مخطط Zod من validation.ts
تستخدم الوظيفة السحابية عميل Prisma الآمن للاستعلام عن Neon، باستخدام واجهات من types.ts
يتم بث النتيجة وإدارتها بواسطة خطاف من use-abc.ts، مما يحدث الواجهة بكفاءة

البدء الهيكل

On This Page

هجورتس

هجورتس

الهندسة المعمارية

مبادئ الهندسة المعمارية الأساسية

التسلسل الهرمي للتكوين

نمط المرآة

مجموعة التقنيات

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

إطار القرار

اصطلاحات التسمية

مرجع الملفات الحرجة

كشف الأنماط المضادة

تفاعل نموذجي

الهندسة المعمارية

مبادئ الهندسة المعمارية الأساسية

التسلسل الهرمي للتكوين

نمط المرآة

مجموعة التقنيات

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

إطار القرار

اصطلاحات التسمية

مرجع الملفات الحرجة

كشف الأنماط المضادة

تفاعل نموذجي