"Explain It Like I Built It" Technical Documentation for Non-Technical Founders

أنت كاتب تقني رفيع المستوى متخصص في جعل الأنظمة المعقدة مفهومة لغير المهندسين. لديك موهبة في استخدام التشبيهات والسرد وتحويل رسوم معمارية إلى قصص.

أحتاج منك تحليل هذا المشروع وكتابة ملف توثيق شامل يسمى `FORME.md` يشرح كل شيء عن هذا المشروع بلغة واضحة.

## سياق المشروع
- **اسم المشروع:** ${name}
- **ما يفعله (جملة واحدة):** [مثال: "منصة SaaS تتيح للمطاعم إدارة طلباتها عبر الإنترنت دون دفع عمولة للمجمّعين"]
- **دوري:** [مثال: "أنا المؤسس / مالك المنتج / المصمم — لا أكتب الكود ولكنني أتخذ جميع قرارات المنتج والهندسة المعمارية"]
- **المكدس التقني (إذا كنت تعرفه):** [مثال: "Next.js, Supabase, Tailwind" أو "لست متأكدًا، اكتشفه من الكود"]
- **المرحلة:** [MVP / الإصدار 1 في الإنتاج / التوسع / إعادة هيكلة نظام قديم]

## قاعدة الكود
[حمّل الملفات، أو قدم المسار، أو الصق الملفات الرئيسية]

## هيكل الوثيقة

اكتب ملف FORME.md بهذه الأقسام، بهذا الترتيب:

### 1. الصورة الكبيرة (نظرة عامة على المشروع)
ابدأ بملخص تنفيذي من 3-4 جمل يمكن لأي شخص فهمه.
ثم قدم:
- المشكلة التي يحلها هذا المشروع ولمن
- كيف يتفاعل المستخدمون معه (رحلة المستخدم بكلمات واضحة)
- تشبيه "لو كان هذا مطعمًا" (أو ما شابه) للنظام بأكمله

### 2. الهندسة المعمارية التقنية — المخطط الأزرق
اشرح كيف تم تصميم النظام ولماذا تم اتخاذ تلك الخيارات.
- ارسم الهندسة المعمارية باستخدام رسم نصي بسيط (مربعات وأسهم)
- اشرح كل طبقة/خدمة رئيسية وكأنك تقوم بجولة في مبنى:
  "هذا هو المطبخ (طبقة API) — كل العمل الحقيقي يحدث هنا.
  تأتي الطلبات من مكتب الاستقبال (الواجهة الأمامية)، وتتم معالجتها هنا،
  وتُخزن النتائج في خزانة الملفات (قاعدة البيانات)."
- لكل قرار معماري، أجب: "لماذا هذا وليس البديل الواضح؟"
- سلط الضوء على أي خيارات ذكية أو غير عادية اتخذها المطور

### 3. هيكل قاعدة الكود — نظام الملفات
حدد تنظيم الملفات والمجلدات للمشروع.
- أظهر شجرة المجلدات (أعلى مستويين أو ثلاثة)
- لكل مجلد رئيسي، اشرح:
  - ما الذي يوجد هنا (بكلمات واضحة)
  - متى يحتاج شخص ما لفتح هذا المجلد
  - كيف يرتبط بالمجلدات الأخرى
- أشر إلى أي اصطلاحات تسمية غير واضحة
- حدد "نقاط الدخول" — الملفات التي تبدأ منها الأمور

### 4. الاتصالات وتدفق البيانات — كيف تتحدث الأشياء مع بعضها البعض
تتبع كيف تتحرك البيانات عبر النظام.
- اختر 2-3 إجراءات مستخدم أساسية (مثل "المستخدم يسجل الدخول"، "المستخدم يضع طلبًا")
- لكل إجراء، استعرض الرحلة الكاملة خطوة بخطوة:
  "عندما ينقر المستخدم على 'وضع الطلب'، إليك ما يحدث خلف الكواليس:
  1. الزر يشغل دالة في [ملف] — فكر في الأمر كقرع جرس
  2. صوت الجرس هذا ينتقل إلى ${api_route} — المطبخ يسمع الطلب
  3. المطبخ يتحقق من [قاعدة البيانات] — هل لدينا المكونات؟
  4. إذا كانت الإجابة نعم، فإنه يرسل تأكيدًا — النادل يحضر الفاتورة"
- اشرح اتصالات الخدمة الخارجية (المدفوعات، البريد الإلكتروني، APIs) وماذا يحدث إذا فشلت
- صف تدفق المصادقة (كيف يعرف التطبيق من أنت؟)

### 5. الخيارات التقنية — صندوق الأدوات
لكل تقنية/مكتبة/خدمة مهمة مستخدمة:
- ما هي (جملة واحدة، بدون مصطلحات فنية)
- ما هي الوظيفة التي تؤديها في هذا المشروع تحديدًا
- لماذا تم اختيارها بدلاً من البدائل (كن محددًا: "نحن نستخدم Supabase بدلاً من Firebase لأن...")
- أي قيود أو مقايضات يجب أن تعرفها
- الآثار المترتبة على التكلفة (طبقة مجانية؟ مدفوعة؟ تعتمد على الاستخدام؟)

صيغها كجدول:
| التقنية | ما تفعله هنا | لماذا هذه | انتبه لـ |
|-----------|------------------|-------------|---------------|

### 6. البيئة والتكوين
اشرح الإعداد دون افتراض معرفة تقنية:
- ما هي متغيرات البيئة الموجودة وماذا يتحكم كل منها (بلغة واضحة)
- كيف تعمل البيئات المختلفة (التطوير مقابل التدريج مقابل الإنتاج)
- "إذا كنت بحاجة إلى تغيير [X]، فستقوم بتحديث [Y] — ولكن كن حذرًا لأن [Z]"
- أي أسرار/مفاتيح والخدمات التي تتصل بها (ليس القيم الفعلية)

### 7. الدروس المستفادة — قصص الحرب
هذا هو القسم الأكثر قيمة. وثّق:

**الأخطاء والإصلاحات:**
- الأخطاء الرئيسية التي واجهتها أثناء التطوير
- ما الذي سببها (مشروحة ببساطة)
- كيف تم إصلاحها
- كيف تتجنب مشاكل مماثلة في المستقبل

**المزالق والألغام:**
- الأشياء التي تبدو بسيطة ولكنها معقدة سراً
- "إذا احتجت يومًا إلى تغيير [X]، فكن حذرًا لأنه يؤثر أيضًا على [Y] و [Z]"
- الديون التقنية المعروفة ولماذا توجد

**الاكتشافات:**
- التقنيات أو الأساليب الجديدة التي تم استكشافها
- ما الذي نجح وما لم ينجح
- "لو كنت سأبدأ من جديد، لكنت..."

**الحكمة الهندسية:**
- أفضل الممارسات التي ظهرت من هذا المشروع
- الأنماط التي أثبتت موثوقيتها
- كيف يفكر المهندسون ذوو الخبرة في هذه المشاكل

### 8. بطاقة مرجعية سريعة
ورقة غش في النهاية:
- كيفية تشغيل المشروع محليًا (خطوة بخطوة، بافتراض عدم وجود إعداد مسبق)
- عناوين URL الرئيسية (الإنتاج، التدريج، لوحات الإدارة، لوحات المعلومات)
- من/أين تذهب عندما يتعطل شيء ما
- الأوامر الأكثر شيوعًا

## قواعد الكتابة — غير قابلة للتفاوض

1. **لا مصطلحات غير مشروحة.** كل مصطلح تقني يحصل على شرح فوري بلغة واضحة أو تشبيه عند الاستخدام الأول. يمكنك استخدام المصطلح التقني بعد ذلك، ولكن يجب أن يفهمه القارئ أولاً.

2. **استخدم التشبيهات بقوة.** قارن الأنظمة بالمطاعم، مكاتب البريد، المكتبات، المصانع، الأوركسترا — أي شيء يجعل المفهوم واضحًا. يجب أن يكون التشبيه متسقًا داخل القسم (لا تنتقل من المطعم إلى المستشفى في منتصف الشرح).

3. **اروي قصة لماذا.** لا تكتفِ بتوثيق ما هو موجود. اشرح لماذا تم اتخاذ القرارات، وما هي البدائل التي تم النظر فيها، وما هي المقايضات التي تم قبولها. "اخترنا X بسبب Y، على الرغم من أن ذلك يعني أننا لا نستطيع بسهولة فعل Z لاحقًا."

4. **كن جذابًا.** استخدم نبرة محادثة، أسئلة بلاغية، روح دعابة خفيفة عند الاقتضاء. يجب أن تكون هذه الوثيقة شيئًا يرغب شخص ما في قراءته بالفعل، وليس شيئًا يُجبر عليه. إذا كان قسم ما مملًا، أعد كتابته حتى لا يكون كذلك.

5. **كن صادقًا بشأن المشاكل.** أشر إلى الديون التقنية، المشكلات المعروفة، وقرارات "فعلنا هذا بسبب ضغط الوقت". هذه الوثيقة تكون أكثر فائدة عندما تكون صادقة منها عندما تكون مصقولة.

6. **ضمن "ما الذي يمكن أن يحدث خطأ" لكل نظام رئيسي.** ليس لإخافة، ولكن للتحضير. "إذا تعطلت خدمة الدفع، إليك ما يحدث وإليك ما يجب فعله."

7. **استخدم الكشف التدريجي.** ابدأ كل قسم بالنسخة البسيطة، ثم تعمق. يجب أن يكون القارئ قادرًا على التوقف في أي نقطة ولا يزال لديه فهم مفيد.

8. **صيغ لسهولة المسح الضوئي.** استخدم العناوين، الكلمات الرئيسية الغامقة، الفقرات القصيرة، والنقاط للقوائم. ولكن استخدم النثر (وليس النقاط) للشروحات والسرد.

## مثال على النبرة

خطأ — جاف ومليء بالمصطلحات:
"ينفذ التطبيق عرضًا من جانب الخادم مع إعادة التوليد الثابت التدريجي، باستخدام Next.js App Router مع React Server Components لتحقيق TTFB الأمثل."

صحيح — واضح وجذاب:
"عندما يزور شخص ما موقعنا، يقوم الخادم ببناء الصفحة مسبقًا قبل إرسالها — مثل مطعم يقوم بإعداد وجبتك قبل وصولك بدلاً من البدء من الصفر عندما تجلس. وهذا ما يسمى 'العرض من جانب الخادم' وهو سبب سرعة تحميل الصفحات. نحن نستخدم Next.js App Router لهذا الغرض، وهو مثل نظام سير عمل المطبخ الذي يقرر ما يتم إعداده مسبقًا وما يتم طهيه حسب الطلب."

خطأ — سرد بدون سياق:
"التبعيات: React 18, Next.js 14, Tailwind CSS, Supabase, Stripe"

صحيح — شرح الفريق:
"فكر في مكدسنا التقني كطاقم، كل عضو له تخصصه:
- **React** هو مصمم الديكور — يبني كل ما تراه على الشاشة
- **Next.js** هو مدير المسرح — ينسق متى وكيف تظهر الأشياء
- **Tailwind** هو قسم الأزياء — يتعامل مع جميع الأنماط المرئية
- **Supabase** هو كاتب الملفات — يخزن ويسترجع جميع بياناتنا
- **Stripe** هو أمين الصندوق — يتعامل مع جميع الأمور المالية بأمان"