نظرة عامة على البنية
هذه الصفحة خريطة مختصرة. التصميم المرجعي، بتدفق البيانات وأسباب كل اختيار، موجود في specs/architecture.md.
الخدمات
يشغّل منزل مكتبة أربع خدمات تتشارك قاعدة بيانات Postgres واحدة للحالة، ووحدة تخزين واحدة للوسائط تضم ملفات الفيديو. تتواصل معها التطبيقات والسحابة الاختيارية.
| الخدمة | اللغة | الدور |
|---|---|---|
| الواجهة البرمجية | Go | REST وGraphQL وWebSocket. المصادقة والأدوار، والمكتبات، وتنسيق البحث، والتحكم في المهام، والإعدادات، وحالة المشاهدة. توقّع روابط البث. |
| البث | Go | أصل HLS وDASH. تحويل الترميز وإعادة التغليف عبر FFmpeg، وخدمة النطاقات، والترجمات المصاحبة، وصور المعاينة، وقنوات التلفاز المباشر. |
| خط المعالجة | Python | الماسح، والفحص، واستخراج الصوت، والتفريغ النصي عبر Whisper (MLX أو faster-whisper أو OpenAI)، والتضمينات، والفهرسة، وتمييز المتحدثين. يستهلك طابور المهام. |
| الويب | React وTypeScript وVite | تطبيق الويب (تطبيق ويب تقدّمي PWA) ودليل المستخدم المدمج في /help. تعرضه تطبيقات الخادم المكتبية. |
| التطبيقات الأصلية | Swift وKotlin | Maktaba Player وMaktaba Remote (iPhone وiPad وMac وAndroid)، وMaktaba TV (Apple TV وAndroid TV)، والمشغّل لنظامي Windows وLinux. |
| مُرحِّل السحابة (اختياري) | Go | طبقة مستضافة للوصول عن بُعد: الهوية، وربط الخوادم، ومُرحِّل HTTP عبر نفق WSS، وتوزيع الإشعارات. موجود في cloud/. |
تجمع maktaba-server الواجهة البرمجية والبث وواجهة الويب في ملف تنفيذي واحد لعمليات
التثبيت؛ وتحمل التطبيقات المكتبية (Tauri) هذا الخادم.
لغة واحدة لكل مجال
تتولى Python التعلّم الآلي، وتتولى Go الخوادم، وتتولى TypeScript الواجهات. تنتمي الميزة الجديدة إلى الخدمة التي تملك الحالة المعنية، ولا تتوزع على أكثر من بيئة تشغيل.
قاعدة البيانات
- تحفظ PostgreSQL 16 مع pgvector الحالة كلها: المكتبات، ومقاطع الفيديو، والنصوص المفرّغة،
وطابور المهام، والمستخدمين، والإعدادات. يعمل البحث النصي الكامل (
tsvector) والبحث الدلالي (pgvector) في قاعدة البيانات نفسها. - تُدعم SQLite في وضع المستخدم الواحد. تُشحن عمليات الترحيل ملفات SQL مرقّمة في
shared/db/migrations/، مع إبقاء نسختي Postgres وSQLite متطابقتين. - يحق لكل خدمة القراءة؛ ولا تكتب في جداول خدمة إلا الخدمة المالكة لها.
كيف تتواصل الخدمات
- من الواجهة البرمجية إلى خط المعالجة: gRPC للعمل الخاص بالاستعلامات، مثل تضمين استعلام
بحث. أما التحكم في المهام بالجملة فيمر عبر Postgres: تُدرج الواجهة البرمجية المهام، ويحجزها
عمال خط المعالجة بالأمر
SELECT ... FOR UPDATE SKIP LOCKED. - من الواجهة البرمجية إلى البث: gRPC لدورة حياة الجلسة والتفاوض على القدرات. توقّع الواجهة البرمجية روابط البث، ويجلب العملاء البيانات مباشرة من خدمة البث عبر HTTPS، فلا تمر حركة الفيديو بالواجهة البرمجية أبدًا.
- الأحداث: ينقل
LISTEN/NOTIFYفي Postgres أحداثًا مثل «تغيّرت حالة مهمة» و«فيديو جديد جاهز» وما شابهها. تحوّلها الواجهة البرمجية إلى إطارات WebSocket للعملاء. لا يوجد وسيط رسائل منفصل. - الملفات: يملك خط المعالجة مراقب نظام الملفات. لا تقرأ خدمة البث الملفات إلا حين يطلبها
طلب ما. تُحفظ الملفات المرافقة المولَّدة (الترجمات المصاحبة والصور المصغّرة) في مجلد مخفي
.maktaba/بجوار كل ملف مصدر، فتبقى المكتبة قابلة للنقل. - العملاء: يستخدم تطبيق الويب والتطبيقات الأصلية الواجهة البرمجية (عقودها في
shared/api/:openapi.yamlومخطط GraphQL) ويشغّلون الفيديو من خدمة البث. - السحابة: يرتبط المنزل بحساب Maktaba Cloud ويُبقي نفقًا صادرًا إلى المُرحِّل، فتصل إليه التطبيقات من خارج المنزل دون فتح منافذ.
مبادئ التصميم
- هوية مبنية على المحتوى. يُعرَّف الفيديو ببصمة BLAKE3 لمحتواه، فلا تؤدي إعادة التسمية أو النقل إلى إعادة المعالجة أبدًا.
- مهام متساوية الأثر وقابلة للاستئناف. يمكن إعادة تشغيل كل مرحلة في خط المعالجة بأمان؛ إذ تُكتب المخرجات في مسار مؤقت ثم يُعاد تسميتها دفعة واحدة.
- مراحل منفصلة. لكل مرحلة في خط المعالجة واجهة صغيرة، ولا تتواصل إلا عبر مخزن المهام، فاستبدال محرك تحويل الكلام إلى نص لا يمس شيئًا آخر.
- تراجع سلس. إذا توقف خط المعالجة تظل المكتبة قابلة للتصفح والبث؛ وإذا توقفت خدمة البث يظل التصفح والبحث يعملان.
ماذا تقرأ بعد ذلك
- تنظيم المستودع للعثور على شيفرة كل خدمة.
- الإعداد المحلي لتشغيلها.
- الملاحم في specs/epics لتصميم كل ميزة.