# البنية

## ما هي

تشرح هذه الصفحة البنية المشتركة الحالية `legacy-shared`. الرسوم ومسار الطلب أدناه يصفان هذا النطاق.

بوابة واحدة على خادمك تستقبل كل طلب، وتتحقق من مفتاح API، ثم تمرّره إلى خدمة Supabase الأصلية في البيئة الصحيحة. لكل بيئة قاعدة بياناتها وAuth وREST خاصة بها؛ أما PostgreSQL نفسه وStorage فعمليتان مشتركتان.

## لماذا

الخيار هو مشاركة المحركات الثقيلة (PostgreSQL وStorage)، وفصل الخدمات التي تحمل هوية البيئة وواجهتها البرمجية (Auth وPostgREST وقاعدة البيانات وحسابات دخولها). Auth وPostgREST خدمتان صغيرتان، وتشغيلهما لكل بيئة يعني ألا تبديل لقاعدة البيانات لحظة الطلب، ولا نسخة معدّلة (fork) من أيٍّ منهما.

بدائل مرفوضة:

- **Auth واحد وPostgREST واحد لكل البيئات**، مع تبديل قاعدة البيانات في كل طلب. لا تدعم أيٌّ من الخدمتين الأصليتين هذا نمطًا معتمدًا، وجعله يعمل يعني إعادة كتابة كود حساس أمنيًا.
- **حزمة كاملة لكل بيئة.** أبقيناها أساسًا لقياس العزل وخيارًا احتياطيًا (PostgreSQL مستقل لكل بيئة)، لكنها تكرر كل المكوّنات.

## كيف بنيناه

![مقارنة بحزمة كاملة لكل مشروع، يتشارك صباربيز بوابة واحدة ومحرك PostgreSQL واحدًا وعملية Storage واحدة، ويشغّل Auth وREST لكل بيئة](https://base.sbarah.com/docs/diagrams/full-stack-vs-shared.ar.svg)

*يعمل PostgreSQL وStorage مرة واحدة، وتضيف كل بيئة قاعدتها ومستأجر Storage وAuth وREST صغيرين خاصين بها.*

![ينتقل الطلب من التطبيق إلى البوابة، فتتحقق من المفتاح للبيئة المذكورة في المسار وترفض فورًا بـ429 أو 503 بدل وضعه في طابور، ثم يصل إلى Auth أو REST في تلك البيئة وحساب دخولها الخاص إلى قاعدتها؛ وتذهب الملفات إلى Storage المشترك مع ترويسة المستأجر](https://base.sbarah.com/docs/diagrams/request-path.ar.svg)

*تفحص البوابة كل طلب مقابل البيئة المذكورة في مساره، وترفض بدل أن تضعه في طابور.*

وهذا التوجيه الكامل، بما فيه مسار الإدارة وعامل التجهيز:

![يصل التطبيق ومتصفح المشغّل إلى وكيل TLS ثم الخادم المحلي، فيوجّه بحسب المسار: /management/auth/v1/* إلى نطاق Auth الإدارة، و/management/* إلى واجهة الإدارة وفهرسها في SQLite، ومسار auth أو rest أو storage لبيئة ما إلى البوابة؛ وتمرر البوابة الطلب إلى Auth أو PostgREST الخاصين بالبيئة أو إلى Storage المشترك، وكلها على قاعدة البيئة في محرك PostgreSQL المشترك؛ ويقرأ عامل التجهيز الفهرس ويشغّل الحاويات المثبّتة](https://base.sbarah.com/docs/diagrams/routing.ar.svg)

*وكيل واحد، وخادم محلي واحد، وثلاثة مسارات.*

**مسار الطلب.** يستدعي التطبيق `/<environment>/rest/v1/...` بمفتاحه العام، ويجوز لخادم أن يرسل مفتاحًا سريًا بدلًا منه. تقرأ البوابة سجل توجيه البيئة (هل هي في الصيانة؟ وأين تعمل؟)، وتطابق المفتاح مع البصمات المحفوظة، وتقبل الطلب إن كان عدد الطلبات الجارية للبيئة دون حدها المتزامن، وتحدّ الجسم بـ1 MiB (أما رفع ملف إلى Storage فيمر كما يصل حتى حد الرفع، 50 MiB افتراضيًا)، ثم تمرّره إلى PostgREST الخاص بتلك البيئة. طلبات Storage تذهب إلى عملية Storage المشتركة الوحيدة، مع ترويسة مستأجر موثوقة تسمّي البيئة. ومقابس Realtime واستدعاءات Edge Functions تسلك المسار نفسه إلى حاويات البيئة الخاصة بها. ولا تمرّر البوابة دون مفتاح API إلا تنزيلات Storage العامة والموقّعة، وخطوات Auth التي يصلها المتصفح برابط (verify وauthorize وcallback)، والدوال المنشورة مع إطفاء `verify_jwt`.

**مسار الإدارة.** يسجّل المشغّلون دخولهم عبر نطاق إدارة مخصص في Auth، لا يكون أبدًا Auth الخاصة ببيئة تطبيق. تستخرج واجهة التحكم هوية الفاعل من هذا الدخول، لا من جسم الطلب أبدًا، وتطبّق أدوار المالك والمدير والمشاهد. ويصل الوكلاء إلى واجهة التحكم نفسها عبر `/v1` و`/mcp` برمز وصول شخصي، فيعملون باسم من أنشأه ([وكلاء الذكاء الاصطناعي](https://base.sbarah.com/docs/guides/agents/)).

**حدود الثقة.** وكيل TLS وحده يواجه الشبكة؛ والخادم المحلي (loopback) وكل حاوية خلفه تستمع على loopback أو على شبكات Docker داخلية، بلا منافذ منشورة. حركة التطبيقات لا تدخل إلا عبر البوابة وتحتاج إلى مفتاح API لتلك البيئة؛ وحركة المشغّلين لا تمر إلا عبر نطاق الإدارة المنفصل وواجهة التحكم. مشغّلو الخادم موثوقون، وزوار التطبيقات غير موثوقين. ما يعنيه ذلك للمكوّنات المشتركة مشروح في [العزل والثقة](https://base.sbarah.com/docs/explain/isolation-and-trust/).

**العمل في الخلفية.** إنشاء بيئة يضع مهمة في الطابور. عامل تجهيز واحد، يمسك قفلًا حصريًا، ينشئ قاعدة البيانات وحسابات الدخول المحصورة، ويكتب قواعد الاتصال، ويشغّل الخدمات. انظر [التجهيز](https://base.sbarah.com/docs/explain/provisioning/).

| مشترك | منفصل لكل بيئة |
|---|---|
| محرك PostgreSQL (عنقود واحد) | قاعدة البيانات، وثلاثة حسابات دخول محصورة للخدمات، وقواعد الاتصال |
| عملية Storage | مستأجر Storage ومفاتيح توقيعه وبياناته الوصفية |
| البوابة وواجهة التحكم | Auth وPostgREST والمفاتيح العامة والسرية وسجل التوجيه |
| المفتاح الجذري لـVault | حاويات Realtime وEdge Functions وStudio، عند تشغيلها |
| معالج الخادم وذاكرته وقرصه | حدود فئة الموارد لكل حاوية |

الكود: [src/control/application.ts](https://github.com/M7MMAD-OMAR/sbarbase/blob/main/src/control/application.ts) (التوجيه بين المسارات الثلاثة)، و[src/gateway/handler.ts](https://github.com/M7MMAD-OMAR/sbarbase/blob/main/src/gateway/handler.ts) و[src/gateway/managed.ts](https://github.com/M7MMAD-OMAR/sbarbase/blob/main/src/gateway/managed.ts) (البوابة)، و[src/gateway/concurrency.ts](https://github.com/M7MMAD-OMAR/sbarbase/blob/main/src/gateway/concurrency.ts) (القبول)، و[src/control/http.ts](https://github.com/M7MMAD-OMAR/sbarbase/blob/main/src/control/http.ts) و[src/control/key-http.ts](https://github.com/M7MMAD-OMAR/sbarbase/blob/main/src/control/key-http.ts) (واجهة الإدارة)، و[src/control/catalog.ts](https://github.com/M7MMAD-OMAR/sbarbase/blob/main/src/control/catalog.ts) (الفهرس)، و[lab/worker.py](https://github.com/M7MMAD-OMAR/sbarbase/blob/main/lab/worker.py) و[lab/durable_runtime.py](https://github.com/M7MMAD-OMAR/sbarbase/blob/main/lab/durable_runtime.py) (بيئة التشغيل). المسارات مسرودة في [مرجع API](https://base.sbarah.com/docs/reference/api/).

## مسار تجريبي لمحرك مستقل

تحدد [مواصفة مكان التشغيل الأصلي](https://github.com/M7MMAD-OMAR/sbarbase/blob/main/docs/engineering/plans/2026-10-03-native-placement-identity.md) بنية `native-dedicated` تستخدم صورة Supabase الأصلية لمحرك مستقل. يربط التصريح في فهرس التحكم هوية البيئة بقاعدة التطبيق وقاعدة الصيانة، مع الفصل بينهما. قبول هذا التصريح للقراءة لا يفعّل التجهيز أو التوجيه أو الاستعادة أو كل الخدمات المستهلكة له.

تسجّل [خطة المنتج](https://github.com/M7MMAD-OMAR/sbarbase/blob/main/docs/engineering/plans/2026-10-03-product-and-portability-plan.md) و[سجل الأدلة](https://github.com/M7MMAD-OMAR/sbarbase/blob/main/docs/engineering/gauntlet-ledger.json) الأجزاء المتحقق منها والفجوات. توقف فحص المهام المجدولة وطلبات HTTP عند اختلاف صلاحيات دوال cron الفعلية عن النموذج المتوقع، قبل تشغيل تلك المهام والطلبات. ولم يُقبل هذا المسار. وهذا المسار التجريبي لا يغيّر حدود البنية المشتركة الموصوفة هنا.

## الحدود

- القبول لكل عملية بوابة، بلا طابور: البيئة المثقلة تأخذ `429`، والخادم المشغول يأخذ `503`. عمليات البوابة المتعددة لا تتشارك العدّادات.
- يمر رفع الملفات كما يصل حتى حد الرفع (50 MiB افتراضيًا)؛ والرفع القابل للاستئناف (TUS) لا يُوجَّه بعد.
- يعمل Realtime وEdge Functions في حاوية لكل بيئة تشغّلهما، ويعمل Studio لكل بيئة عند الطلب. أما مجمّع الاتصالات (pooler) وcron فلم يدخلا بعدُ في البنية العاملة.
- كل العمليات تتشارك فهرسًا محليًا واحدًا؛ ولا تنسيق بين عدة خوادم.

## للتعمق

- [طبقة التحكم](https://github.com/M7MMAD-OMAR/sbarbase/blob/main/docs/engineering/CONTROL-PLANE.md)، و[التوجيه الدائم](https://github.com/M7MMAD-OMAR/sbarbase/blob/main/docs/engineering/PERSISTENT-ROUTING.md)، و[حمل البوابة الزائد](https://github.com/M7MMAD-OMAR/sbarbase/blob/main/docs/engineering/GATEWAY-OVERLOAD.md)، و[تصريف البوابة](https://github.com/M7MMAD-OMAR/sbarbase/blob/main/docs/engineering/GATEWAY-DRAIN.md).
- [بيئة التشغيل المشتركة](https://github.com/M7MMAD-OMAR/sbarbase/blob/main/docs/engineering/COMBINED-RUNTIME.md) و[سياسة الموارد](https://github.com/M7MMAD-OMAR/sbarbase/blob/main/docs/engineering/RESOURCE-POLICY.md).
- [مواصفة دمج Studio](https://github.com/M7MMAD-OMAR/sbarbase/blob/main/docs/engineering/STUDIO-INTEGRATION.md): كيف يشغّل المشغّل Studio الأصلي لكل بيئة عند الطلب.