Awlak Benjah
متتبّع للدرجات العلمية والمعدلات لطلاب الجامعة اللبنانية يعمل دون اتصال: تطبيق Expo يحسب على الهاتف المعدلات الموزونة بالوحدات الدراسية والتعويض وحكم النجاح، مع واجهة NestJS برمجية للقوالب والنسخ الاحتياطية واشتراك شطّور، ولوحة تحكم على الويب لإدارته.




نظرة عامة على البنية
أولك بنجح؟ («هل سأنجح؟» بالعامية اللبنانية) متتبّع للدرجات العلمية والمعدلات لطلاب الجامعة اللبنانية. يمثّل التطبيق الدرجة العلمية سنواتٍ وفصولًا ومقرراتٍ وعلاماتٍ من 100، ويحسب على الجهاز نفسه المعدلات الموزونة بالوحدات الدراسية والتعويض وحكم النجاح أو الرسوب لكل سنة، دون أي اتصال بالشبكة ودون حساب.
الصعوبة أن قواعد النجاح ليست معادلة واحدة. فقد يُحكم على السنة فصلًا بفصل، حيث ينجح المقرر بدرجة 50 وتُعوَّض الدرجة من 40 إلى 49 حين يبلغ متوسط الفصل 55 بوحداته كاملة، أو على المعدل الموزون للسنة، ويمكن لدرجة علمية واحدة أن تجمع الطريقتين. كل قاعدة استراتيجية (strategy) في حزمة تقييم مشتركة، لها دالة حكم (judge)، وخطة (plan) تقود دليل النجاح، وحكم «غير معروف» صريح، واختبار ثوابت (invariant) واحد يُشغَّل على كل سلوك، فلا يمكن أن يختلف التطبيق والعرض التوضيحي على الويب والاختبارات.
وحول هذه النواة التي تعمل دون اتصال تقوم واجهة خلفية اختيارية. تقدّم واجهة NestJS البرمجية قوالب الدرجات العلمية، وتحفظ الحسابات والنسخ الاحتياطية، وتقرّر الاشتراك المدفوع («شطّور» عند الطلاب) من استحقاق يكتبه webhook من RevenueCat. يُعرَّف كل مسار مرة واحدة عقدًا في oRPC، ويستهلكه عبر عميل مُنمَّط كلٌّ من التطبيق ولوحة التحكم على الويب، حيث يُدار المستخدمون والاشتراكات والإصدارات، إلى جانب محادثة ذكاء اصطناعي تقرأ الحسابات وسجل التدقيق عبر أدوات MCP.
داخل التطبيق
يعمل التطبيق محليًا أولًا، لذا يحمل منطق المجال الذي كانت الواجهة الخلفية لتحمله عادةً. ينقسم كوده إلى طبقات لا تتّجه استيراداتها إلا إلى الأسفل، وتفرض dependency-cruiser هذه القواعد في كل فحص بدل أن تُترك للمراجعة.
- أربع عشرة وحدة وخريطة اعتماديات واحدة. تعرض كل وحدة (الدرجات العلمية، السنوات،
الفصول، المقررات، العلامات، التقارير، الحساب، النسخ الاحتياطي وغيرها) ملف
index.tsللشاشات وملفmodel.tsلنموذجها الخالي من أي إطار عمل، ولا يمكنها استيراد إلا الوحدات المدرجة لها. يعرف الابن أسلافه ولا يعرفونه، فإضافة اعتمادية قرارٌ يُتّخذ في المراجعة لا مجرّد تسهيل. - نمط MVVM بأنياب. تكتفي الـViews بالعرض، وتحمل خطافات الـViewModel المنطق. يُفشل سكربت
الفحص عند أي عملية حسابية داخل View (
.filter(،Math.، أوuseStateتُهيَّأ من خاصية واردة)، ويمنع الـlint في ملفات الـViews الخطافات التي تحمل منطقًا، مثلuseEffectوuseMemo. - وحدة عمل واحدة لكل حالة استخدام. تتحقّق حالة الاستخدام من مدخلاتها، وتعمل داخل معاملة SQLite واحدة، وتُرجع أخطاءً مُنمَّطة تحوّلها الشاشات إلى رسائل مترجمة.
- مُصرّف React مُفعَّل، لذا قواعد الـlint الخاصة به أخطاء: المكوّن الذي يخالف إحداها يفقد تحسينه بصمت.
يشير كل سهم إلى وحدة يحقّ للأخرى استيرادها (جزء من خريطة الاعتماديات). تقع وحدات التركيب، مثل التقارير وsetup وsettings، في الأعلى، ولا تستوردها أي وحدة ميزات.
واجهة خلفية قائمة على العقود
تتشارك الواجهة البرمجية ولوحة التحكم والتطبيق مصدر حقيقة واحدًا لكل مسار.
- NestJS 12 مع Drizzle فوق PostgreSQL، وجلسات تُقرأ من Redis، وbetter-auth لرموز البريد
الإلكتروني وتسجيل الدخول عبر Apple وGoogle والتحقق بخطوتين للمشرفين، وكل خطأ يُعاد على شكل
{ code, message }كي تترجم الواجهات الرمز بدل أن تعرض الرسالة الإنجليزية. - مسارات بإصدارات تحت
/v1. تواصل التطبيقات المثبّتة استدعاء ما صدرت به، لذا يصبح التغيير الكاسر إصدارًا جديدًا، ويرفض نظام CI أي تغيير كاسر لا يحمل الوسم المخصّص لذلك. - الخصوصية عقدٌ عند كل إصدار. لا يرسل التطبيق شيئًا عن الطالب ما لم ينشئ حسابًا، وأي تغيير يُخرج بيانات من الجهاز يحدّث سياسة الخصوصية في طلب الدمج نفسه.
- لوحة التحكم (Vite وReact وTanStack Router وTable) تدير المستخدمين والاشتراكات والقوالب والإصدارات والسجلات والأعطال وعمليات النشر من مكان واحد، فتجلب بيانات Sentry وRevenueCat إليها بدل الإحالة إليها. تقرأ محادثة الذكاء الاصطناعي فيها عبر أدوات MCP وتصوغ ملاحظات الإصدار ونصوص المتاجر، وتنتظر كل عملية كتابة موافقة أحد المشرفين.
التكامل والنشر المستمران (CI/CD)
كل تغيير، مهما صغر، يسلك الطريق نفسه: مسألة (issue) على GitHub، ثم فرع، ثم طلب دمج يُدمج
بطريقة squash، ثم بيئة الاختبار (staging)، ثم إصدار ينشر الإنتاج. لا يُدفع أي شيء إلى main
مباشرةً.
من المسألة إلى الإنتاج
دورة حياة طلب الدمج
ما الذي يشغّله CI
- لا يُفحص إلا ما تغيّر. تسأل مهمة
Changesأداة Turborepo عن الحزم التي يمسّها طلب الدمج، ومعها كل ما يعتمد عليها، ولا تعمل مهمة أي تطبيق إلا إذا تأثّر. لذا تُعيد حزمة مشتركة فحص كل تطبيق يستخدمها. - فحوص كل تطبيق خطوات في مهمة واحدة (lint، قواعد الاعتماديات، الأنواع، الاختبارات، البناء)، لأن GitHub تحتسب كل مهمة بالدقيقة التي تبدأ فيها. خفّض هذا الخيار الفاتورة إلى النصف مقارنةً بمهمة لكل فحص. ومع ذلك يُبلغ كل فحص عن نتيجته حتى لو فشل فحص سابق، بينما لا يعمل البناء إلا إذا نجحت الفحوص كلها.
- ذاكرة مؤقتة واحدة في مكانين. يتشارك CI والفحص المحلي ذاكرة Turborepo المؤقتة البعيدة، فالمهمة التي نجحت مدخلاتها نفسها في أي مكان تُعاد في ثانية بدل أن تُشغَّل من جديد. ويحتفظ Prettier أيضًا بذاكرة مؤقتة مبنية على المحتوى.
- لا يعمل CI إلا على طلبات الدمج. لا يتقدّم
mainإلا بعمليات دمج squash، وكانت إعادة فحص كل دمج تستهلك أكثر من نصف دقائق الخطة المجانية. - فحص العقود يعيد توليد مستند OpenAPI، ويقارنه بمستند
main، ويُفشل طلب الدمج الذي يكسر/v1ما لم يحمل وسمًا يعلن أن الكسر مقصود. - عملٌ حديث خفّض مدة طلب دمج نموذجي للواجهة البرمجية من نحو 8.5 دقيقة إلى 4.5. صارت صورة Docker تُبنى بجانب الفحوص بدل أن تنتظرها، وانخفض زمن اختبارات الواجهة البرمجية البالغ عددها 431 من 146 ثانية إلى 49، بمنح vitest عاملًا (worker) لكل نواة واستيراد التطبيق مرة واحدة لكل عامل بدل مرة لكل ملف اختبار.
الإطلاق
- بيئة staging تتبع
main: كل دمج ينشر التطبيقات التي مسّها، والواجهة البرمجية أولًا، لأن كود الويب الجديد قد يستدعي مسارات جديدة. - الإنتاج إصدار. يُبقي release-please طلب إصدار واحدًا مفتوحًا، برقم الإصدار التالي وسجل تغييرات مستخلصَين من عناوين الدمج. ودمجه يُنشئ الوسم، وينشر الإنتاج، ويبني تطبيق iOS على EAS لـTestFlight حين يتغيّر التطبيق.
- تُشحن الواجهة البرمجية حاويةً دون سجل صور (registry): تُرسل الصورة إلى الخادم عبر SSH بمفتاح لا يستطيع إلا تشغيل سكربت النشر. تعمل الترحيلات قبل التبديل، فيبقى الإصدار القديم في الخدمة إن فشل ترحيل، ويعيد فحص الصحة الفاشل الصورة السابقة.
- حول خط الإنتاج: لا يقترح Renovate إلا التحديثات المؤشّر عليها في لوحته، ويعمل
pnpm auditوexpo-doctorأسبوعيًا، وتُنسخ قاعدتا البيانات احتياطيًا كل ليلة إلى Cloudflare R2.
بُني بمساعدة وكلاء الذكاء الاصطناعي
كُتب معظم الكود باستخدام Claude Code، وفق القواعد نفسها التي يتبعها أي مساهم بشري.
- كل مهمة مسألة على GitHub، موسومة وموضوعة في لوحة المشروع، ويُسجَّل فيها التكليف وأدلة
القبول تعليقاتٍ. ومهارتان كُتبتا لهذا المستودع،
github-issuesوship-changes، تحملان العملية من المسألة حتى الإنتاج. - 28 مهارة (skill) لوكلاء الذكاء الاصطناعي مضمّنة في المستودع، مثبّتة ببصمتها في ملف قفل
وتُراجَع كالكود:
expo-uiمن Expo، وأفضل ممارسات React Native وagent-deviceمن Callstack لقيادة المحاكيات، ومهارات العقود من oRPC، وUniwind، وأدلة الأمان من Better Auth، ومهارات الحركة والتصميم من Emil Kowalski، وgoldieللقطات المتاجر. أما المكتبات التي تشحن مهاراتها بنفسها، مثل drizzle-kit وTanStack Router، فيربطها pnpm بالإصدار المثبّت. - ضوابط بدل الثقة. يجمع ملف
AGENTS.mdلكل تطبيق الأعراف المتّبعة، ويمرّر خطافٌ الـlint على كل ملف يعدّله الوكيل ويعيد إليه الأخطاء، وتوقف قواعد البنية وفحص الـViews وفحص العقود أي تغيير خاطئ أيًّا كان كاتبه. - خوادم MCP لوثائق Better Auth وSentry وdrizzle-kit تمنح الوكلاء السياق نفسه الذي يبحث عنه المطوّر.
الميزات الرئيسية:
- نموذج بيانات يعمل دون اتصال على
expo-sqliteعبر Drizzle ORM، يُستورد فيه القالب في معاملة (transaction) واحدة - سلوكيات النجاح (
credit-basedوyear-average) استراتيجياتٌ في@awlak-benjah/grading، يتشاركها التطبيق والعرض التوضيحي على الويب والاختبارات - دليل نجاح لكل مقرر مفتوح، ومع شطّور الدرجة التي يحتاجها كل جزء من أجزاء العلامة
- قوالب درجات علمية تقدّمها الواجهة البرمجية: المجانية متاحة للجميع، والمدفوعة مقفلة خلف صفحة الاشتراك
- حساب مجاني للنسخ الاحتياطي اليدوي والاستعادة؛ ويضيف شطّور النسخ الاحتياطي التلقائي وتقسيم المقررات
- مشتريات داخل التطبيق عبر RevenueCat، سنوية ومدى الحياة، تُمنح استحقاقًا على الحساب
- الإنجليزية والفرنسية والعربية، من اليمين إلى اليسار في العربية، مع الوضعين الفاتح والداكن وأداة للشاشة الرئيسية
- عناصر iOS أصلية عبر
@expo/ui، مع تخطيطات React Native وواجهة Liquid Glass - لوحة تحكم على الويب للمستخدمين والاشتراكات والقوالب، يصوغ فيها نموذج الذكاء الاصطناعي ملاحظات المتاجر بثلاث لغات
التقنيات المستخدمة:
- الهاتف: Expo SDK 58، React Native، Expo Router، @expo/ui، Uniwind، Reanimated، expo-widgets
- البيانات: expo-sqlite، Drizzle ORM، Zustand، TanStack Query، Zod
- الواجهة البرمجية: NestJS 12، oRPC، better-auth، PostgreSQL، Redis، Resend، Vercel AI SDK
- الويب: Vite، React، TanStack Router، TanStack Table
- المدفوعات والتشغيل: RevenueCat، Sentry، Cloudflare Workers، Docker على خادم VPS خلف Caddy، نسخ احتياطية ليلية لقاعدة البيانات إلى R2
- الأدوات: Turborepo، pnpm، TypeScript، oxlint، dependency-cruiser، Vitest، knip، release-please، Renovate
بالأرقام (تشرين الثاني/نوفمبر 2026): 603 commit منذ تموز/يوليو 2026، و232 طلب دمج مدموجًا، و13 إصدارًا، ونحو 1,300 اختبار (342 في التطبيق، و178 في حزمة التقييم، و431 في الواجهة البرمجية، و197 في لوحة التحكم، و159 في الموقع التعريفي)، و17 سير عمل على GitHub Actions.
المستودع خاص. التطبيق قادم إلى iOS وAndroid، وموقعه التعريفي على awlak-benjah.com.