شخصيصعب

Awlak Benjah

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

— نظرة عامة

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

apps/api · NestJS 12

packages

apps/mobile · Expo SDK 58

عميل مُنمَّط

عميل مُنمَّط

webhook

الشاشات
عناصر @expo/ui الأصلية، Uniwind

وحدات الميزات
الدرجات العلمية، السنوات، المقررات، العلامات، الدليل

expo-sqlite + Drizzle

أداة الشاشة الرئيسية

grading
سلوكيات النجاح

contracts
مسارات oRPC

schemas
Zod

الحسابات
better-auth

القوالب، النسخ الاحتياطية، الاستحقاقات

PostgreSQL

Redis

apps/web
لوحة التحكم + عرض توضيحي للطلاب

apps/showcase
Astro

RevenueCat

Cloudflare Workers

أولك بنجح؟ («هل سأنجح؟» بالعامية اللبنانية) متتبّع للدرجات العلمية والمعدلات لطلاب الجامعة اللبنانية. يمثّل التطبيق الدرجة العلمية سنواتٍ وفصولًا ومقرراتٍ وعلاماتٍ من 100، ويحسب على الجهاز نفسه المعدلات الموزونة بالوحدات الدراسية والتعويض وحكم النجاح أو الرسوب لكل سنة، دون أي اتصال بالشبكة ودون حساب.

الصعوبة أن قواعد النجاح ليست معادلة واحدة. فقد يُحكم على السنة فصلًا بفصل، حيث ينجح المقرر بدرجة 50 وتُعوَّض الدرجة من 40 إلى 49 حين يبلغ متوسط الفصل 55 بوحداته كاملة، أو على المعدل الموزون للسنة، ويمكن لدرجة علمية واحدة أن تجمع الطريقتين. كل قاعدة استراتيجية (strategy) في حزمة تقييم مشتركة، لها دالة حكم (judge)، وخطة (plan) تقود دليل النجاح، وحكم «غير معروف» صريح، واختبار ثوابت (invariant) واحد يُشغَّل على كل سلوك، فلا يمكن أن يختلف التطبيق والعرض التوضيحي على الويب والاختبارات.

وحول هذه النواة التي تعمل دون اتصال تقوم واجهة خلفية اختيارية. تقدّم واجهة NestJS البرمجية قوالب الدرجات العلمية، وتحفظ الحسابات والنسخ الاحتياطية، وتقرّر الاشتراك المدفوع («شطّور» عند الطلاب) من استحقاق يكتبه webhook من RevenueCat. يُعرَّف كل مسار مرة واحدة عقدًا في oRPC، ويستهلكه عبر عميل مُنمَّط كلٌّ من التطبيق ولوحة التحكم على الويب، حيث يُدار المستخدمون والاشتراكات والإصدارات، إلى جانب محادثة ذكاء اصطناعي تقرأ الحسابات وسجل التدقيق عبر أدوات MCP.

داخل التطبيق

يعمل التطبيق محليًا أولًا، لذا يحمل منطق المجال الذي كانت الواجهة الخلفية لتحمله عادةً. ينقسم كوده إلى طبقات لا تتّجه استيراداتها إلا إلى الأسفل، وتفرض dependency-cruiser هذه القواعد في كل فحص بدل أن تُترك للمراجعة.

modules/ · 14 شريحة عمودية

تُنفّذ المنافذ

عبر index.ts العام فقط

app/ + shell/
المسارات، التخطيطات، المزوّدات

العرض
Views + ViewModels

التطبيق
حالات الاستخدام، المنافذ

المجال
بلا إطار عمل

البنية التحتية
مستودعات Drizzle

core/
قاعدة البيانات، i18n، الاستعلامات، الأخطاء، السجلات

ui/
نظام التصميم، يدعم RTL

shared/
أدوات مساعدة طرفية

  • أربع عشرة وحدة وخريطة اعتماديات واحدة. تعرض كل وحدة (الدرجات العلمية، السنوات، الفصول، المقررات، العلامات، التقارير، الحساب، النسخ الاحتياطي وغيرها) ملف index.ts للشاشات وملف model.ts لنموذجها الخالي من أي إطار عمل، ولا يمكنها استيراد إلا الوحدات المدرجة لها. يعرف الابن أسلافه ولا يعرفونه، فإضافة اعتمادية قرارٌ يُتّخذ في المراجعة لا مجرّد تسهيل.
  • نمط MVVM بأنياب. تكتفي الـViews بالعرض، وتحمل خطافات الـViewModel المنطق. يُفشل سكربت الفحص عند أي عملية حسابية داخل View (.filter(، Math.، أو useState تُهيَّأ من خاصية واردة)، ويمنع الـlint في ملفات الـViews الخطافات التي تحمل منطقًا، مثل useEffect وuseMemo.
  • وحدة عمل واحدة لكل حالة استخدام. تتحقّق حالة الاستخدام من مدخلاتها، وتعمل داخل معاملة SQLite واحدة، وتُرجع أخطاءً مُنمَّطة تحوّلها الشاشات إلى رسائل مترجمة.
  • مُصرّف React مُفعَّل، لذا قواعد الـlint الخاصة به أخطاء: المكوّن الذي يخالف إحداها يفقد تحسينه بصمت.

setup / settings

التقارير

النسخ الاحتياطي

العلامات

الحساب

المقررات

الفصول

السنوات

الدرجات العلمية

يشير كل سهم إلى وحدة يحقّ للأخرى استيرادها (جزء من خريطة الاعتماديات). تقع وحدات التركيب، مثل التقارير وsetup وsettings، في الأعلى، ولا تستوردها أي وحدة ميزات.

واجهة خلفية قائمة على العقود

تتشارك الواجهة البرمجية ولوحة التحكم والتطبيق مصدر حقيقة واحدًا لكل مسار.

يُقارن بـ main في كل PR

packages/schemas
Zod، مسار فرعي لكل مجال

packages/contracts
مسارات oRPC + openapi.json

apps/api
تنفّذ كل مسار

packages/api-client
عميل مُنمَّط

apps/mobile

لوحة تحكم apps/web

فحص التغييرات الكاسرة

  • 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 مباشرةً.

من المسألة إلى الإنتاج

مسألة على GitHub
في لوحة المشروع

فرع في
worktree خاص به

الفحص المحلي
pnpm check

طلب دمج
بعنوان اصطلاحي

CI على طلب الدمج

دمج squash

النشر إلى staging
التطبيقات المتأثرة فقط

release-please
يحدّث طلب الإصدار

دمج الإصدار
وسم + إصدار GitHub

النشر إلى الإنتاج
الواجهة البرمجية ثم الويب والموقع التعريفي

بناء iOS على EAS
إلى TestFlight

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

release-pleasestagingذاكرة Turborepo المؤقتةسير عمل CIGitHubإغلاق المسألة وحذف الفرع والـworktreeالمطوّرpnpm check، وإعادة تشغيل المهام المخزّنة1فتح طلب الدمج مرتبطًا بمسألته2تشغيل CI على commit الدمج3اكتشاف الحزم المتأثرة4إعادة المهام التي لم تتغيّر5فحوص لكل تطبيق، فحص العقود، فحص العنوان6دمج squash بعد نجاح الفحوص7نشر التطبيقات المتأثرة8فحص الصحة يُظهر commit الدمج9تحديث طلب الإصدار وسجل التغييرات10

ما الذي يشغّله CI

api

api

contracts

mobile

web

showcase

pull_request

Changes
turbo ls --affected

Repo
Prettier، knip

العنوان الاصطلاحي

فحوص الواجهة البرمجية
lint، الاعتماديات، الأنواع، الاختبارات

صورة الواجهة البرمجية
بناء + اختبار تشغيل

العقود
التغييرات الكاسرة

فحوص الهاتف

فحوص الويب + البناء

فحوص الموقع التعريفي + البناء

  • لا يُفحص إلا ما تغيّر. تسأل مهمة Changes أداة Turborepo عن الحزم التي يمسّها طلب الدمج، ومعها كل ما يعتمد عليها، ولا تعمل مهمة أي تطبيق إلا إذا تأثّر. لذا تُعيد حزمة مشتركة فحص كل تطبيق يستخدمها.
  • فحوص كل تطبيق خطوات في مهمة واحدة (lint، قواعد الاعتماديات، الأنواع، الاختبارات، البناء)، لأن GitHub تحتسب كل مهمة بالدقيقة التي تبدأ فيها. خفّض هذا الخيار الفاتورة إلى النصف مقارنةً بمهمة لكل فحص. ومع ذلك يُبلغ كل فحص عن نتيجته حتى لو فشل فحص سابق، بينما لا يعمل البناء إلا إذا نجحت الفحوص كلها.
  • ذاكرة مؤقتة واحدة في مكانين. يتشارك CI والفحص المحلي ذاكرة Turborepo المؤقتة البعيدة، فالمهمة التي نجحت مدخلاتها نفسها في أي مكان تُعاد في ثانية بدل أن تُشغَّل من جديد. ويحتفظ Prettier أيضًا بذاكرة مؤقتة مبنية على المحتوى.
  • لا يعمل CI إلا على طلبات الدمج. لا يتقدّم main إلا بعمليات دمج squash، وكانت إعادة فحص كل دمج تستهلك أكثر من نصف دقائق الخطة المجانية.
  • فحص العقود يعيد توليد مستند OpenAPI، ويقارنه بمستند main، ويُفشل طلب الدمج الذي يكسر /v1 ما لم يحمل وسمًا يعلن أن الكسر مقصود.
  • عملٌ حديث خفّض مدة طلب دمج نموذجي للواجهة البرمجية من نحو 8.5 دقيقة إلى 4.5. صارت صورة Docker تُبنى بجانب الفحوص بدل أن تنتظرها، وانخفض زمن اختبارات الواجهة البرمجية البالغ عددها 431 من 146 ثانية إلى 49، بمنح vitest عاملًا (worker) لكل نواة واستيراد التطبيق مرة واحدة لكل عامل بدل مرة لكل ملف اختبار.

الإطلاق

الويب والموقع التعريفي

نشر الواجهة البرمجية

فشل

بناء الصورة
buildx + ذاكرة الطبقات

إرسالها عبر SSH
إلى أمر مفروض

تشغيل الترحيلات

تبديل الحاوية

فحص الصحة

إعادة الصورة السابقة

wrangler deploy
إلى Cloudflare Workers

  • بيئة 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.

— التقنيات
TypeScriptReact NativeExpoAstroTailwind CSSTurborepoSQLiteDrizzle ORMCloudflareNestJSPostgreSQLReactViteZodiOSpnpmRevenueCatoRPCBetter AuthTanStackSentry