انتقل إلى المحتوى
إغلاق
الرئيسية

المشهد 1 من 14: Aissam Portfolio

aissam-web

دراسة حالة · منصتي الخاصة

Aissam Portfolio

الموقع الذي تقرؤه وما يشغّله: موقع عام بثلاث لغات، ولوحة إدارته، والـ API الخاص به، وendpoint لـ MCP لعملاء الذكاء الاصطناعي.

الدور
المالك والمهندس الوحيد، من الـ API إلى الصفحات
السنة
2026

التحدي

ثلاثة تطبيقات تتقاسم الأنواع نفسها، وشخص واحد يُبقيها متوافقة، وعميل ذكاء اصطناعي يستطيع أن يفعل ما تفعله لوحة الإدارة.

بالأرقام

  1. 103أداة MCP، لم تُكتب أيّ منها يدويًا: 102 مسارًا من لوحة الإدارة تُقرأ من سجل المسارات، إضافة إلى whoami.
  2. 193مسارًا في الـ API موزّعة على 13 وحدة، يسمّي كلًّا منها RAI: دوره ووحدته وعمليته.
  3. 9workspaces في مستودع واحد: ثلاثة تطبيقات، وأربع حزم، وحزمتان للأدوات.
  4. 333commit، من الأول في 5 شتنبر 2026 إلى الأخير في 16 أكتوبر.

مستودع واحد

تغيير عقد البيانات يصل إلى التطبيقات الثلاثة

يتقاسم الـ API ولوحة الإدارة والموقع workspace واحدًا بـ Bun وTurborepo، لأن البُنى التي تتبادلها سبق أن تباعدت مرة. كان التحقق من الصلاحيات (scopes) موجودًا مرتين: في إطار عمل الـ API، ومنسوخًا يدويًا في لوحة الإدارة. كانت النسختان متطابقتين، ولم يكن هناك ما يُلزمهما بذلك.

تحمل ثلاث حزم الآن كل ما يعبر بين التطبيقات: ‎@app/contracts فيها نوع كل payload، و‎@app/scopes فيها مطابِق الصلاحيات، و‎@app/content فيها مخططات كتل Markdown ومدقق المستندات. وحزمة ‎@app/contracts وحدها يستوردها 90 ملفًا مصدريًا في الـ API، و88 في لوحة الإدارة، و51 في الموقع.

تُدمج هذه الحزم في كود المتصفح وتُشغَّل تحت Bun، فلا يحق لأيّ منها استيراد Hono ولا وحدات Node المدمجة ولا React. وأي تغيير في إحداها تغيير في عقد البيانات بين التطبيقات، يُتحقَّق منه في الـ API ولوحة الإدارة والموقع معًا.

الاعتماديات

من يعتمد على ماذا

تتجه الأسهم من الحزمة إلى ما تستورده، كما يصرّح به كل package.json. حزمتا contracts وscopes لا تستوردان شيئًا على الإطلاق، وcontent لا تضيف إلا zod، وcore لا تعمل إلا تحت Bun ولا يستعملها إلا الـ API. أما حزمتا الأدوات فلا تعتمدان على أيّ منها.

apps/api@app/backend · Bunapps/bo@app/backoffice · Viteapps/fe@app/web · Next.jspackages/core@app/core · Bun onlypackages/content@app/content · zodpackages/contractsno dependenciespackages/scopesno dependenciesRoute · AppBuilderscopesSatisfyAllvalidateDocumentLocale · Localizedpayload typesvalidateDocumentscope matcherpayload typesFlowSpec · ReplaySpecpayload types

لوحة الإدارة

كل ما يعرضه الموقع يُحرَّر هنا

تُحرَّر الملاحظات ووثائق المشاريع ودراسات الحالة والصفحة الرئيسية وخريطة المسار ونصوص الموقع والوسائط والتصنيفات في تطبيق واحد بـ Vite وReact 19. الإنجليزية هي المصدر، والفرنسية والعربية تُكتبان بجانبها.

يتحقق محرر Markdown من المستند بالمدقق نفسه الذي يشغّله الـ API قبل الحفظ، ومعاينته هي الموقع نفسه داخل إطار يتبع تمرير المحرر.

الشاشات محمية بالصلاحية التي تحتاجها مساراتها، وتتحقق منها لوحة الإدارة بالمطابِق نفسه الذي يستعمله الـ API. وحساب واحد فقط يحمل دور sysadmin.

مسار ملاحظة

ملاحظة، من المحرر إلى الصفحة

  1. الخطوة 1 من 5

    الكتابة

    متن Markdown لكل لغة، في لوحة الإدارة. الإنجليزية إلزامية، والفرنسية والعربية بجانبها ويمكن أن تأتيا لاحقًا.

  2. الخطوة 2 من 5

    التحقق

    زر التحقق يشغّل validateDocument من ‎@app/content داخل المحرر: كتل flow وreplay وfaq يجب أن تكون JSON يطابق مواصفاتها، والعرض التجريبي غير المعروف يُنبَّه إليه. وأخطاء الـ API تظهر في اللوحة نفسها.

  3. الخطوة 3 من 5

    الحفظ

    يشغّل الـ API المدقق نفسه قبل الكتابة، ويردّ على أول خطأ بـ 422 مع رقم السطر. وتُحفظ نسخة من الملاحظة كما كانت، ويأتي عدد الكلمات ومدة القراءة من المدقق.

  4. الخطوة 4 من 5

    النشر

    رابط معاينة موقّع يفتح المسودة على الموقع لمدة 15 دقيقة. والنشر يحفظ نسخة، ويمسح ذاكرة الملاحظات والتصنيفات المؤقتة، ويُخطر IndexNow لكل لغة حين يكون المفتاح مضبوطًا.

  5. الخطوة 5 من 5

    العرض

    يقرأ الموقع الملاحظة من الـ API ويمرّرها عبر سلسلة معالجة واحدة على الخادم: GFM والتنبيهات والتضمينات وShiki للكود، وكتل flow وreplay وdemo وfaq تتحول إلى مكوّنات. أما Mermaid فيُرسم في المتصفح.

المعمارية

ثلاثة تطبيقات، API واحد، وworker واحد

يقرأ الموقع مسارات guest، وتكتب لوحة الإدارة عبر مسارات sysadmin، ويصل عميل الذكاء الاصطناعي إلى المسارات نفسها عبر endpoint الـ MCP. أما مهام التحليلات فتخرج من الـ API إلى عملية worker خاصة بها.

Shared packagescontracts · scopes · contentSiteNext.js 16 · en · fr · arBack officeVite · React 19AI clientOAuth or mcp_pat_ tokenMCP endpointPOST /api/v1/mcpAPIHono on Bun · 193 routesMongoDBMongooseRediscache · BullMQ queuesWorkerAPP_ROLE=worker · analyticscontracts · contentcontracts · content · scopescontracts · content · scopesguest routessysadmin routestools/callapp.fetchMongoosecache · queue.addprojection · rollup

من المسار إلى الأداة

كيف يصبح مسار في لوحة الإدارة أداة MCP

  1. الخطوة 1 من 5

    المسار

    يُصرَّح به مرة واحدة: الطريقة والمسار والـ RAI والأدوار والصلاحيات ووصف ومخطط zod. والوصف هو ما يقرؤه النموذج ليختار الأداة.

  2. الخطوة 2 من 5

    السجل

    عند الإقلاع، تُجمع مسارات كل الوحدات في سجل واحد. والتصريحات نفسها تغذّي ذاكرة الصلاحيات المؤقتة وأدوات التطوير ومجموعة Postman مولَّدة.

  3. الخطوة 3 من 5

    الإسقاط

    يصبح كل مسار sysadmin: أداةً تحمل اسم الـ RAI دون الدور: sysadmin:cases:update يصير cases_update. مستثنى منها: وحدة users، وتنظيف الوسائط، وتصدير CSV.

  4. الخطوة 4 من 5

    تسجيل الدخول

    يسجّل عميل الذكاء الاصطناعي دخوله عبر OAuth، مع PKCE والتسجيل الديناميكي للعملاء، ويوافق عليه المالك من شاشة في لوحة الإدارة. أما رمز mcp_pat_ الملصوق فلا يعمل إلا على هذا الـ endpoint.

  5. الخطوة 5 من 5

    التنفيذ

    يتحول الاستدعاء إلى app.fetch على المسار الحقيقي، مع JWT صالح لرحلة واحدة ذهابًا وإيابًا: نفس المصادقة وفحص الصلاحيات وحدّ الطلبات والتحقق كما في المتصفح. وكل إنشاء يسجّل created_via: mcp.

إعادة

نداء MCP واحد، معادًا

نداء cases_update حقيقي، متتبَّع عبر الكود. المدد وسيط 50 نداءً، مقيس داخل العملية على جهاز تطوير. انتقل إلى حالة الفشل لترى رفض المخطط يعود بصيغة يستطيع النموذج تصحيحها.

إعادة

الموقع العام

قصة واحدة تُروى بالتمرير، بثلاث لغات

الصفحة الرئيسية قصة واحدة يرويها التمرير: صورة تنغلق في بطاقة، والطريق على خريطة، وجملة تُضاء، وحلقة من دراسات الحالة بـ CSS 3D، ثم الأعمال، وسنة من المساهمات، والملاحظات، وطريقة للتواصل.

دراسة الحالة سجلّ وليست صفحة: قائمة مرتبة من المشاهد مأخوذة من فهرس من أحد عشر نوعًا، أنواعها معرّفة في ‎@app/contracts، ويتحقق منها الـ API، ويرسم كلَّ نوع منها مكوّنٌ خاص به. وهذه الصفحة واحدة منها.

تتقاسم الإنجليزية والفرنسية والعربية كل المسارات، والصفحات العربية من اليمين إلى اليسار منذ أول عرض. وتُحصى الزيارات بنظام التحليلات الخاص بالموقع، الذي يحترم Do Not Track وGlobal Privacy Control ويصل إلى الـ API عبر proxy على النطاق نفسه. ولا يوجد أي متتبّع خارجي.

التحليلات

الموقع يحصي زياراته بنفسه

لا يُجمع أي شيء قبل أن يقبل الزائر شريط الموافقة، ويكفي كل من Do Not Track وGlobal Privacy Control وخيار الرفض الخاص بالموقع وحده لإسكات أداة التتبع. والهوية مؤشر عشوائي في sessionStorage يُشفَّر بملح من جهة الخادم، أما عنوان IP فيُستعمل مرة واحدة لمعرفة البلد ولا يُخزَّن أبدًا.

يرسل الموقع مشاهدات الصفحات ونبضات التفاعل وأحداثًا مسمّاة مثل تحميل السيرة الذاتية أو إكمال عرض تجريبي، في دفعات لا تتجاوز 20 حدثًا عبر proxy ‎/a/collect على النطاق نفسه. ويكتبها الـ API بالإضافة فقط، فلا تغيّر الدفعة المعادة شيئًا، ويعلّم الروبوتات والمعاينات والنطاقات غير الإنتاجية لتستبعدها التقارير.

الجلسات والتجميعات اليومية إسقاطات تعيد بناءها مهام BullMQ في عملية الـ worker: ماسح يعمل كل دقيقة، وتجميع يعيد حساب يوم كامل ويُرفض إن سبقه تجميع أحدث. ولوحة الإدارة تقرؤها، مع الأهداف ومسارات التحويل ورحلات الزوار. وتُحفظ الأحداث الخام 90 يومًا، والتجميعات 395.

بُني بـ

  • Bun
  • Hono
  • MongoDB
  • Mongoose
  • Redis
  • BullMQ
  • Zod
  • MCP
  • Next.js 16
  • React 19
  • next-intl
  • Vite
  • TanStack Router
  • Tailwind CSS
  • Turborepo
  • PM2

أين وصل

متاح على aissamirhir.com

إعداد PM2 واحد يصرّح بالعمليات الأربع، الـ API وworker التحليلات ولوحة الإدارة والموقع، للإنتاج وللـ staging. ما زال قادمًا: صندوق لرسائل التواصل في لوحة الإدارة؛ فالنموذج اليوم يُحيل الرسالة إلى خدمة خارجية أو يفتح بريد الزائر.

لنتحدث عن مشروعك
مسار صفحات في كل لغة، من الصفحة الرئيسية إلى دراسة الحالة هذه.
13
شاشة في لوحة الإدارة خلف تسجيل دخول واحد، منها إحدى عشرة للتحليلات.
34
الدراسة التاليةKeforo Studio