تنظيم المستودع

مكتبة مستودع واحد يضم كل الخدمات والتطبيقات والمواصفات والأدوات. تسرد هذه الصفحة المجلدات الرئيسية. تصفّحها على GitHub.

الخدمات

المجلد	ما يحويه
`api/`	خدمة الواجهة البرمجية بلغة Go: معالجات REST وGraphQL وWebSocket (`api/internal/handlers/`)، والمصادقة، والأدوار، والبرمجيات الوسيطة، ومنطق العنقود والتحديثات. لها ملف `go.mod` خاص بها.
`streaming/`	خدمة البث بلغة Go: أصل HLS/DASH، وتحويل الترميز وإعادة التغليف عبر FFmpeg، وقنوات التلفاز المباشر. لها ملف `go.mod` خاص بها.
`pipeline/`	خط المعالجة بلغة Python (`maktaba_pipeline`): الماسح، والتفريغ النصي، والتضمينات، والمفهرس، وعمال المهام. يُدار عبر `uv` (`pyproject.toml` و`uv.lock`)؛ والاختبارات في `pipeline/tests/`.
`cloud/`	مُرحِّل السحابة الاختياري (Go): الهوية، وربط الخوادم، ومُرحِّل النفق، والإشعارات. له وحدته وعمليات ترحيله وملف Dockerfile الخاص به.
`cmd/`	الملفات التنفيذية الرئيسية: `maktaba-server` (الواجهة البرمجية والبث وواجهة الويب في ملف واحد) و`maktaba-launcher` (يشغّل الخادم ويسلّمه ويتولى التحديثات).

المجلد	ما يحويه
`web/`	تطبيق الويب بلغة React (`web/src/`، ودليل المستخدم في `web/src/help/` والنصوص في `web/src/i18n/`)، ونظام التصميم ورموزه (`web/design-system/`)، وتطبيق ويب السحابة، وتطبيق الويكي، والحزم في `web/packages/` (ومنها `devportal` التي تبني maktaba.dev). يُدار عبر `pnpm`.
`apps/apple/`	تطبيقات SwiftUI: Maktaba Player وMaktaba Remote لأجهزة iPhone وiPad وMac، وحزمة Swift المشتركة `MaktabaKit`.
`apps/android/`	تطبيقات Jetpack Compose: المشغّل وجهاز التحكم، مبنية على وحدة `client` قابلة للنقل ووحدة `core` مشتركة.
`apps/tv/`	Maktaba TV لنظام tvOS (Swift) ولنظام Android TV (Kotlin).
`apps/desktop-player/`	مشغّل مبني بـ Compose for Desktop لنظامي Windows وLinux.
`apps/desktop/`	تطبيق Tauri المكتبي لأنظمة macOS وWindows وLinux، الذي يحمل الخادم.
`apps/mobile/`	أغلفة Capacitor أقدم لنظامي iOS وAndroid.

يضم shared/ ما تستخدمه أكثر من خدمة:

shared/api/: openapi.yaml ومخطط GraphQL، المصدر الوحيد المعتمد لعقد الواجهة البرمجية.
shared/db/migrations/: عمليات ترحيل SQL مرقّمة، بنسختي Postgres وSQLite جنبًا إلى جنب.
shared/go/ وshared/log/ وshared/metrics/ وshared/tracing/ وshared/health/: مكتبات مشتركة للسجلات والمقاييس والتتبع وفحص السلامة.
shared/testtier/: مستويات الاختبار المشتركة بين اللغات، وميزانياتها، وحراس الإدخال والإخراج.
shared/fixtures/ وshared/testdata/: بيانات ثابتة تستخدمها الاختبارات في مختلف الخدمات.

المجلد	ما يحويه
`specs/`	المصدر المعتمد للتصميم: `architecture.md` ومجلد لكل ملحمة في `specs/epics/` (ملف README والقصص والخطط).
`docs/`	وثائق المشغّلين والمطورين: الاختبار، والتحديثات، والعنقود، والعتاد، والويكي المولَّد، وأدلة المطورين هذه في `docs/developers/`.
`tests/`	مجموعات اختبار عابرة للخدمات: مستوى الاختبار الشامل (`tests/e2e/`) ومجموعة الأداء (`tests/perf/`) اللتان تعملان على حزمة compose.

المجلد أو الملف	ما يحويه
`Makefile`	نقاط الدخول المعتمدة. يستدعي التكامل المستمر الأهداف نفسها. شغّل `make help` لرؤية القائمة.
`deploy/`	حزم Docker Compose (`deploy/compose/`)، والتغليف، وأدوات المراقبة، ونشر مُرحِّل السحابة، وإعدادات المستودع.
`tools/`	أدوات المطورين: `affected-tests` (بوابة شحن الاختبارات مع الشيفرة)، و`ci` (فحوص مرشّحات المسارات)، و`test-budget`، و`migration-lint`، و`log-lint`، و`coverage-floor`، و`release`، و`dev` (سكربتات البيئة المحلية)، و`rehearsal` وغيرها.
`.github/`	مسارات عمل التكامل المستمر (`workflows/ci.yml` والمسارات التي يستدعيها)، ومرشّحات المسارات (`ci-paths.yml`)، وقالب طلب الدمج.
`.githooks/`	خطّاف `pre-push` الذي يشغّل بوابة الاختبارات المتأثرة.
`pyproject.toml`	إعدادات pytest الجذرية لمجموعات الاختبار في `tests/`. أما إعدادات حزمة خط المعالجة نفسها ففي `pipeline/pyproject.toml`.

ابحث عن الملحمة في specs/epics/ واقرأ ملف README الخاص بها.
تذكر الملحمة الخدمة التي تملك الحالة؛ ابحث في مجلد تلك الخدمة.
لنقاط الوصول في الواجهة البرمجية، ابدأ من shared/api/openapi.yaml، ثم الحزمة المقابلة في api/internal/handlers/.

راجع نظرة عامة على البنية لترى كيف تتكامل الأجزاء.