System Requirements Document for azure-project

1. Introduction

azure-project هو واجهة ويب محلية عربية لإدارة نماذج Ollama المحلية واستخدامها في البحث. المنتج موجّه لمشغّلي النماذج المحلية والباحثين الذين يعملون مع Ollama على جهازهم، ويريدون بديلاً عن الطرفية لإدارة النماذج (عرض/تحميل/حذف) ثم استخدام النماذج المُدارة لإرسال استعلامات بحثية وقراءة الردود — كل ذلك دون مغادرة الواجهة ودون الاعتماد على API خارجي.

المنتج لا يقدّم نماذج سحابية، ولا يبيع اشتراكات، ولا ينفّذ إعداد أدوات على جهاز المستخدم. نطاقه هو بناء تطبيق/واجهة محلية تتعامل مع Ollama المحلي على http://localhost:11434 وعبر endpoint المتوافق مع OpenAI API على http://localhost:11434/v1.

2. System Overview

azure-project تطبيق ويب محلي بواجهة عربية كاملة (RTL) يتصل بـ Ollama المحلي على http://localhost:11434. يعرض التطبيق النماذج المتوفرة محلياً، ويتيح تحميل نموذج جديد ومتابعة تقدّم التحميل، وحذف نموذج، واختيار نموذج مُدار لإرسال استعلامات بحثية وقراءة الردود الناتجة عبر endpoint المتوافق مع OpenAI API على http://localhost:11434/v1.

الفاعلون البشريون (قائمة مغلقة):

• مشغّل النماذج المحلية (Ollama Operator)
• الباحث عبر النماذج المحلية (Local-Model Researcher)

الفاعلون غير البشريين:

• Ollama المحلي (خدمة خارجية محلية على http://localhost:11434) — مالك تنفيذ عمليات النماذج والاستدلال.
• endpoint المتوافق مع OpenAI API على http://localhost:11434/v1 — واجهة الاستدلال التي يستدعيها التطبيق.

السلوك المقبول الحالي:

• عرض النماذج المتوفرة محلياً.
• تحميل نموذج جديد إلى Ollama من داخل الواجهة ومتابعة تقدّم التحميل.
• حذف نموذج.
• اختيار نموذج مُدار واستخدامه في البحث عبر إرسال استعلام وعرض الرد.

الاستثناءات الضيقة:

• لا اعتماد على API خارجي؛ التشغيل محلي بالكامل.
• 8080.ai لا ينفّذ إعداد أدوات على جهاز المستخدم؛ النطاق هو بناء تطبيق/واجهة.
• التوافق مع Claude Code غير مضمون 100% وقد يحتاج طبقة وسيطة (proxy مثل LiteLLM) لتحويل الصيغة؛ بعض النماذج الخفيفة لا تدعم tool calling. هذا قيد على مسار التوافق مع Claude Code، وليس حظراً على إدارة النماذج أو البحث عبر Ollama.

2a. Product Interpretation and Delivery Boundary

azure-project تطبيق ويب محلي بالكامل. الواجهة تعمل في المتصفح على الجهاز نفسه، وتتصل مباشرة بخدمة Ollama المحلية على http://localhost:11434. لا توجد حسابات سحابية، ولا مصادقة مركزية، ولا اعتماد على خدمات خارجية. الوصول إلى الصفحات الأربع (الرئيسية، النماذج، تحميل نموذج، البحث) متاح محلياً دون تسجيل دخول، لأن التشغيل محلي على جهاز المستخدم نفسه.

حدود التسليم الحالية: إدارة النماذج (عرض/تحميل/حذف) واستخدام النماذج المُدارة في البحث، كل ذلك عبر Ollama المحلي.

حدود مستقبلية (خارج النطاق الحالي): التوافق الكامل مع Claude Code عبر Ollama، وأي طبقة وسيطة (proxy مثل LiteLLM) لتحويل الصيغة، ودعم tool calling للنماذج الخفيفة — كلها غير مضمونة 100% وتبقى خارج التسليم الحالي.

2b. Source Content Inventory

لا ينطبق — لا يوجد توجيه مرجعي من نوع content_source في هذا المشروع.

2c. Page Content and Component Coverage

الرئيسية

• المعلومات والحالة: نقطة الدخول العامة التي تشرح الواجهة العربية المحلية لإدارة نماذج Ollama واستخدامها في البحث. تعرض حالة الاتصال بـ Ollama على http://localhost:11434، وعدد النماذج المُثبَّتة، والأمر الحقيقي ollama serve القابل للنسخ.
• الإجراءات الأساسية: الانتقال إلى النماذج، الانتقال إلى تحميل نموذج، الانتقال إلى البحث، نسخ أمر ollama serve.
• الإجراءات المساندة: عرض حالة الاتصال الحيّة (نقطة برتقالية نابضة عند النشاط، رمادي باهت مع رسالة «Ollama غير متاح» عند فشل الاتصال).
• كيانات المجال: حالة الاتصال بـ Ollama، عدد النماذج المُثبَّتة، أمر التشغيل.
• مسؤوليات المكوّنات:
  • عنوان رئيسي مقسوم على لونين: «نماذجك المحلية» بالعاجي و«تحت السيطرة» بالبرتقالي #FF5A1F بنفس الحجم 72px.
  • بطاقة حالة حيّة في عمود ضيق (320px): نقطة برتقالية نابضة + «Ollama متصل» + localhost:11434 بخط Mono + عدد النماذج المُثبَّتة كرقم كبير 56px.
  • سطر أمر ollama serve بخط Mono قابل للنقر للنسخ.
  • مخطط تخطيطي بخط 1.5px يُظهر مسار الطلب: المتصفح ← localhost:8080 ← Ollama ← localhost:11434/v1، مع نقاط برتقالية على نقاط الاتصال.
• الحالات: تحميل (جارٍ فحص الاتصال بـ Ollama)، نجاح (الاتصال قائم وعدد النماذج معروض)، خطأ (Ollama غير متاح — تتحول بطاقة الحالة إلى رمادي باهت مع رسالة واضحة)، استرداد (إعادة المحاولة عند عودة الاتصال).

النماذج

• المعلومات والحالة: جدول حقيقي يعرض النماذج المتوفرة محلياً في Ollama مع اسم النموذج، الحجم بالميغابايت، العائلة، تاريخ السحب، والحالة. يوفر سياق إدارة النماذج بما في ذلك حذف نموذج واختيار نموذج للاستخدام.
• الإجراءات الأساسية: حذف نموذج، اختيار نموذج للاستخدام في البحث (الانتقال إلى البحث بالنموذج المُحدد).
• الإجراءات المساندة: تحديث قائمة النماذج، الانتقال إلى تحميل نموذج عند عدم وجود نماذج.
• كيانات المجال: النموذج (الاسم، الحجم بالميغابايت، العائلة، تاريخ السحب، الحالة).
• مسؤوليات المكوّنات:
  • جدول بصفوف بارتفاع 56px، محاذاة أرقام لليسار، عنوان عمود بأحرف كبيرة صغيرة وتباعد واسع.
  • أرقام جدولية بخط IBM Plex Mono.
  • عند التحويم على صف: شريط برتقالي بعرض 2px على حافة الصف اليمنى، وأزرار «بحث» و«حذف» كنص فقط بلا صناديق.
  • «بصمة الحجم»: رسم صغير من أشرطة رأسية متجاورة في كل بطاقة نموذج، أطوالها مشتقة من حجم النموذج الفعلي بالميغابايت نسبةً لأكبر نموذج مُثبَّت.
• الحالات: تحميل (جارٍ جلب قائمة النماذج من Ollama)، فارغ (لا توجد نماذج مُثبَّتة — دعوة للانتقال إلى تحميل نموذج)، نجاح (الجدول معروض)، خطأ (تعذّر الاتصال بـ Ollama — رسالة واضحة مع إعادة المحاولة)، استرداد (تحديث القائمة بعد عودة الاتصال).

تحميل نموذج

• المعلومات والحالة: مساحة مستقلة لتحميل نموذج جديد إلى Ollama من داخل الواجهة ومتابعة عملية التحميل. نموذج من عمود واحد بعرض 560px مع سجل تحميل حي أسفله.
• الإجراءات الأساسية: إدخال اسم/وسم النموذج المطلوب تحميله، بدء التحميل، متابعة تقدّم التحميل.
• الإجراءات المساندة: إلغاء التحميل الجاري، الانتقال إلى النماذج بعد اكتمال التحميل.
• كيانات المجال: طلب التحميل (اسم النموذج، الحالة، النسبة المئوية، السجل).
• مسؤوليات المكوّنات:
  • نموذج إدخال من عمود واحد بعرض 560px.
  • شريط تقدّم بزوايا قائمة 2px يتحرك بسلاسة خطية مع رقم النسبة يتغير فورياً بخط Mono.
  • سجل تحميل حي أسفل النموذج.
  • نقطة برتقالية 8px تنبض بإيقاع 1s أثناء سحب النموذج وتتوقف تماماً عند الانتهاء.
• الحالات: تحميل (جارٍ سحب النموذج — شريط تقدّم ونسبة مئوية)، فارغ (لم يبدأ أي تحميل)، نجاح (اكتمل التحميل — دعوة للانتقال إلى النماذج)، خطأ (فشل التحميل — رسالة واضحة مع إمكانية إعادة المحاولة)، استرداد (إعادة بدء التحميل أو إلغاؤه).

البحث

• المعلومات والحالة: مساحة البحث التي تتيح اختيار نموذج محلي مُدار وإرسال الاستعلامات وعرض الردود الناتجة عبر Ollama المحلي. مقسومة إلى عمود اختيار النموذج (280px) + عمود المحادثة المرن، مع سطر حالة سفلي ثابت يعرض اسم النموذج المُحدد وزمن آخر استجابة.
• الإجراءات الأساسية: اختيار نموذج مُدار، إرسال استعلام بحثي، قراءة الرد.
• الإجراءات المساندة: مسح المحادثة، الانتقال إلى النماذج لتغيير النموذج.
• كيانات المجال: النموذج المُحدد، الاستعلام، الرد، زمن الاستجابة.
• مسؤوليات المكوّنات:
  • عمود اختيار النموذج (280px) يعرض النماذج المُدارة المتوفرة.
  • عمود المحادثة المرن لعرض الاستعلامات والردود.
  • سطر حالة سفلي ثابت يعرض اسم النموذج المُحدد وزمن آخر استجابة بخط Mono.
  • نقطة برتقالية 8px تنبض بإيقاع 1s أثناء توليد الرد وتتوقف تماماً عند الانتهاء.
• الحالات: تحميل (جارٍ توليد الرد — نقطة نابضة)، فارغ (لم يُرسل أي استعلام بعد)، نجاح (الرد معروض مع زمن الاستجابة)، خطأ (تعذّر الاتصال بـ Ollama أو فشل التوليد — رسالة واضحة مع إعادة المحاولة)، استرداد (إعادة إرسال الاستعلام أو تغيير النموذج).

3. Functional Requirements

FR-01 — عرض النماذج المتوفرة محلياً

As a مشغّل النماذج المحلية (Ollama Operator) I should عرض قائمة النماذج المتوفرة محلياً في Ollama so that أعرف ما هو مُثبَّت على جهازي قبل أي عملية إدارة أو بحث.

• Provenance: explicit
• Trigger/Input: فتح صفحة النماذج.
• Observable result: جدول يعرض اسم النموذج، الحجم بالميغابايت، العائلة، تاريخ السحب، والحالة.
• Access state: محلي، دون تسجيل دخول.
• Failure/recovery: عند تعذّر الاتصال بـ Ollama، تظهر رسالة واضحة مع إمكانية إعادة المحاولة.
• Continuation: الانتقال إلى تحميل نموذج أو البحث.

FR-02 — تحميل نموذج جديد

As a مشغّل النماذج المحلية (Ollama Operator) I should تحميل نموذج جديد إلى Ollama من داخل الواجهة so that أضيف نموذجاً خفيفاً (مثل Qwen3) دون استخدام الطرفية.

• Provenance: explicit
• Trigger/Input: إدخال اسم/وسم النموذج في صفحة تحميل نموذج وبدء التحميل.
• Observable result: شريط تقدّم بزوايا قائمة 2px يتحرك بسلاسة خطية مع رقم النسبة يتغير فورياً بخط Mono، وسجل تحميل حي.
• Access state: محلي، دون تسجيل دخول.
• Failure/recovery: عند فشل التحميل، تظهر رسالة واضحة مع إمكانية إعادة المحاولة أو الإلغاء.
• Continuation: عند اكتمال التحميل، دعوة للانتقال إلى النماذج.

FR-03 — حذف نموذج

As a مشغّل النماذج المحلية (Ollama Operator) I should حذف نموذج من النماذج المتوفرة محلياً so that أحرّر مساحة التخزين وأزيل النماذج غير المستخدمة.

• Provenance: explicit
• Trigger/Input: اختيار «حذف» على صف نموذج في صفحة النماذج.
• Observable result: اختفاء النموذج من الجدول بعد تأكيد الحذف.
• Access state: محلي، دون تسجيل دخول.
• Failure/recovery: عند فشل الحذف، تظهر رسالة واضحة ويبقى النموذج في الجدول.
• Continuation: تحديث قائمة النماذج.

FR-04 — اختيار نموذج مُدار للاستخدام في البحث

As a الباحث عبر النماذج المحلية (Local-Model Researcher) I should اختيار نموذج محلي مُدار من قائمة النماذج so that أستخدمه في إرسال استعلامات بحثية.

• Provenance: explicit
• Trigger/Input: اختيار نموذج من عمود اختيار النموذج (280px) في صفحة البحث، أو النقر على «بحث» في صف نموذج في صفحة النماذج.
• Observable result: ظهور اسم النموذج المُحدد في سطر الحالة السفلي الثابت.
• Access state: محلي، دون تسجيل دخول.
• Failure/recovery: عند عدم وجود نماذج مُدارة، تظهر دعوة للانتقال إلى تحميل نموذج.
• Continuation: إرسال استعلام بحثي.

FR-05 — إرسال استعلام بحثي وقراءة الرد

As a الباحث عبر النماذج المحلية (Local-Model Researcher) I should إرسال استعلام بحثي إلى النموذج المحلي المُحدد وقراءة الرد so that أحصل على نتائج بحث من النموذج المحلي دون مغادرة الواجهة.

• Provenance: explicit
• Trigger/Input: كتابة استعلام في عمود المحادثة في صفحة البحث وإرساله.
• Observable result: ظهور الرد في عمود المحادثة، مع نقطة برتقالية 8px تنبض بإيقاع 1s أثناء التوليد وتتوقف تماماً عند الانتهاء، وزمن آخر استجابة في سطر الحالة السفلي.
• Access state: محلي، دون تسجيل دخول.
• Failure/recovery: عند تعذّر الاتصال بـ Ollama أو فشل التوليد، تظهر رسالة واضحة مع إمكانية إعادة الإرسال.
• Continuation: إرسال استعلام آخر أو تغيير النموذج.

FR-06 — عرض حالة الاتصال بـ Ollama

As a مشغّل النماذج المحلية (Ollama Operator) I should رؤية حالة الاتصال بـ Ollama على http://localhost:11434 كحقيقة دائمة so that أعرف فوراً ما إذا كانت الخدمة متاحة.

• Provenance: required_inference
• Trigger/Input: فتح أي صفحة.
• Observable result: نقطة برتقالية نابضة عند النشاط + «Ollama متصل» + localhost:11434 بخط Mono في الشريط الجانبي الأيمن؛ وتتحول إلى رمادي باهت مع رسالة «Ollama غير متاح» عند فشل الاتصال.
• Access state: محلي، دون تسجيل دخول.
• Failure/recovery: عرض الحالة غير المتصلة بوضوح دون إشعار عابر.
• Continuation: إعادة المحاولة عند عودة الاتصال.

FR-07 — عرض عدد النماذج المُثبَّتة

As a مشغّل النماذج المحلية (Ollama Operator) I should رؤية عدد النماذج المُثبَّتة كرقم كبير so that أعرف حجم مكتبتي المحلية بنظرة واحدة.

• Provenance: required_inference
• Trigger/Input: فتح صفحة الرئيسية.
• Observable result: رقم كبير 56px بخط Mono يعرض عدد النماذج المُثبَّتة.
• Access state: محلي، دون تسجيل دخول.
• Failure/recovery: عند تعذّر الاتصال، يظهر الرقم كغير متاح.
• Continuation: الانتقال إلى النماذج.

FR-08 — نسخ أمر تشغيل Ollama

As a مشغّل النماذج المحلية (Ollama Operator) I should نسخ الأمر الحقيقي ollama serve بنقرة so that أشغّل الخدمة المحلية بسرعة عند الحاجة.

• Provenance: required_inference
• Trigger/Input: النقر على سطر الأمر بخط Mono في صفحة الرئيسية.
• Observable result: نسخ الأمر إلى الحافظة.
• Access state: محلي، دون تسجيل دخول.
• Failure/recovery: عند فشل النسخ، يظهر تنبيه واضح.
• Continuation: لصق الأمر في الطرفية.

FR-09 — عرض مسار الطلب

As a مشغّل النماذج المحلية (Ollama Operator) I should رؤية مخطط مسار الطلب so that أفهم كيف يمر الاستعلام من المتصفح إلى Ollama.

• Provenance: required_inference
• Trigger/Input: فتح صفحة الرئيسية.
• Observable result: مخطط تخطيطي بخط 1.5px يُظهر: المتصفح ← localhost:8080 ← Ollama ← localhost:11434/v1، مع نقاط برتقالية على نقاط الاتصال.
• Access state: محلي، دون تسجيل دخول.
• Failure/recovery: لا ينطبق (عنصر معلوماتي ثابت).
• Continuation: لا ينطبق.

FR-10 — عرض بصمة الحجم لكل نموذج

As a مشغّل النماذج المحلية (Ollama Operator) I should رؤية بصمة حجم بصرية لكل نموذج so that أقارن أحجام النماذج بنظرة واحدة.

• Provenance: required_inference
• Trigger/Input: عرض صفحة النماذج.
• Observable result: رسم صغير من أشرطة رأسية متجاورة في كل بطاقة نموذج، أطوالها مشتقة من حجم النموذج الفعلي بالميغابايت نسبةً لأكبر نموذج مُثبَّت.
• Access state: محلي، دون تسجيل دخول.
• Failure/recovery: لا ينطبق (عنصر بصري مشتق من البيانات).
• Continuation: لا ينطبق.

4. User Personas

مشغّل النماذج المحلية (Ollama Operator)

• سياق المنتج: شخص يعمل محلياً مع Ollama ويريد إدارة النماذج المتوفرة (تحميل/حذف/عرض) بدل التعامل مع الطرفية في كل مرة، ثم استخدام النماذج المُدارة في البحث.
• الهدف الأساسي: أن تكون لديه واجهة واحدة تُظهر النماذج المتوفرة وتتيح إدارتها واستخدامها في البحث.
• المسؤوليات المقبولة: عرض النماذج المتوفرة، تحميل نموذج جديد ومتابعة تقدّم التحميل، حذف نموذج، اختيار نموذج للاستخدام في البحث.
• المدخلات والقرارات: اسم/وسم النموذج المطلوب تحميله، قرار الحذف، قرار اختيار النموذج للبحث.
• التفاعل مع المشاركين الآخرين: يشارك الباحث عبر النماذج المحلية في نفس مكتبة النماذج المحلية؛ النماذج التي يحمّلها المشغّل تصبح متاحة للباحث.
• النجاح الملحوظ: جدول النماذج يعرض الحجم والعائلة وتاريخ السحب والحالة، وشريط التقدّم يعمل أثناء التحميل، والحذف يزيل النموذج من الجدول.

الباحث عبر النماذج المحلية (Local-Model Researcher)

• سياق المنتج: شخص يريد إرسال استعلامات بحثية إلى نموذج محلي خفيف (مثل Qwen3) عبر Ollama وقراءة الردود، مع الحفاظ على الخصوصية المحلية وعدم الاعتماد على API خارجي.
• الهدف الأساسي: أن يحصل على نتائج بحث من النموذج المحلي دون مغادرة الواجهة.
• المسؤوليات المقبولة: اختيار نموذج محلي مُدار، إرسال استعلام بحثي، قراءة الرد وزمن الاستجابة.
• المدخلات والقرارات: نص الاستعلام، قرار اختيار النموذج المناسب للاستعلام.
• التفاعل مع المشاركين الآخرين: يعتمد على النماذج التي حمّلها مشغّل النماذج المحلية؛ إذا لم توجد نماذج مُدارة، يُوجَّه إلى تحميل نموذج.
• النجاح الملحوظ: الرد يظهر في عمود المحادثة، والنقطة البرتقالية تنبض أثناء التوليد وتتوقف عند الانتهاء، وزمن آخر استجابة معروض في سطر الحالة السفلي.

5. Core User Flows

Flow 1 — عرض النماذج المتوفرة (مشغّل النماذج المحلية)

1. يفتح المشغّل صفحة الرئيسية ويرى حالة الاتصال بـ Ollama على http://localhost:11434 وعدد النماذج المُثبَّتة.
2. ينتقل إلى صفحة النماذج.
3. يرى جدولاً بصفوف بارتفاع 56px يعرض اسم النموذج، الحجم بالميغابايت، العائلة، تاريخ السحب، والحالة، مع أرقام جدولية بخط Mono وبصمة حجم لكل نموذج.
4. عند التحويم على صف، يظهر شريط برتقالي بعرض 2px على حافة الصف اليمنى، وتظهر أزرار «بحث» و«حذف» كنص فقط.
5. النتيجة الملحوظة: قائمة النماذج المتوفرة محلياً معروضة بالكامل.
6. الاستمرار: ينتقل إلى تحميل نموذج أو البحث.
7. الفشل والاسترداد: إذا تعذّر الاتصال بـ Ollama، تظهر رسالة واضحة مع إمكانية إعادة المحاولة.

Flow 2 — تحميل نموذج جديد (مشغّل النماذج المحلية)

1. ينتقل المشغّل إلى صفحة تحميل نموذج.
2. يُدخل اسم/وسم النموذج المطلوب (مثل Qwen3) في نموذج الإدخال من عمود واحد بعرض 560px.
3. يبدأ التحميل.
4. النتيجة الملحوظة: شريط تقدّم بزوايا قائمة 2px يتحرك بسلاسة خطية مع رقم النسبة يتغير فورياً بخط Mono، وسجل تحميل حي أسفله، ونقطة برت