عن المشروع

إطار عمل Croco Framework هو إطار عمل TypeScript مبني على Node.js يتعامل مع AWS Lambda وAPI Gateway كعناصر أساسية (first-class citizens). يقدم نفسه في ملف README كإطار عمل "ذو توجهات محددة (opinionated)"، حيث يقوم بتقسيم حدود الحزم حسب الأدوار بشكل صريح لمعالجة صعوبة الحفاظ على اتساق البنية المعمارية في المشاريع الكبيرة. تُصنف الحزم إلى 6 أدوار: Kernel (أساس تشغيل إطار العمل: framework-context, framework-module)، وContracts (عقود النطاق/البروتوكول المستقلة عن المزود: repository-core, protocols-rest, telemetry-api)، وPlugins (تنفيذ العقود وربط البيئة: tx-drizzle, transports-http, preset-node)، وApplication (وحدات التطبيق وجذر التكوين)، وProfiles (مجموعات plugins/module المعتمدة: presentation-preset)، وTooling (البناء، توليد الكود، الاختبار، وCLI). لا تعتمد Kernel وContracts على Plugins محددة، وتعتمد معلومات الأدوار على packageRoles في docs/package-catalog.json. يتميز الإطار بالتمييز بين Host وTransport وBuild Target. يمتلك Host دورة حياة عملية Node أو استدعاء Lambda أو Workers fetch (مثل preset-node, preset-lambda, preset-cloudflare)، بينما يقوم Transport بتنفيذ أسطح البروتوكولات مثل HTTP وGraphQL وRPC، أما Build Target فهو عقد Tooling يحدد نقطة الدخول، ومجلد المخرجات، وتنسيق الوحدة، وقيود التجميع. يمكن لـ Host واحد ربط عدة استدعاءات Transport. من حيث الوظائف، يوفر الإطار أحداث نطاق DDD (events-core) وRegisterEventHandler، ومعاملات Transactional بأسلوب Unit of Work (tx-core، انتشار AsyncLocalStorage)، وتفصيل استجابات المشكلات بناءً على RFC 7807 (problems-core)، ومزخرفات لإعادة المحاولة والاسترداد (Retryable, Recover — retry-core)، وTrace لإنشاء OpenTelemetry Span (telemetry-api)، وحاوية DI تعتمد على المزخرفات (framework-context). يتم تعريف متحكمات REST باستخدام مزخرفات Controller/Get/Post، ويتم تكوين معالج Lambda عبر createApp وcreateLambdaHost. يستهدف الإطار نطاق SaaS من خلال توفير حزم عقود للفوترة، والاستحقاقات، والرصيد، والقياس، وحالة العميل، بالإضافة إلى حزم تكامل ومزودين مثل Polar وClerk وDrizzle وPostHog وQStash. تنص الوثائق على مبدأ عدم إخفاء الفشل كخطأ عام أو تراجع صامت، بل نمذجته عبر Problem، وretry، وtimeout، وcircuit breaker، وidempotency، وexhaustive handling. يمكن البدء باستخدام npx create-croco-app@latest لإنشاء الهيكل (مثلاً: --goal saas-api)، والتحقق من عقود REST وتدفقات SaaS في الذاكرة عبر pnpm demo:smoke دون الحاجة لاعتمادات خارجية، كما يمكن تشغيل مثال يتضمن Auth وMetering في examples/quick-start-lambda باستخدام pnpm dev. وفقاً لملف README، يتتبع الكتالوج 120 حزمة عامة، ويثبت 18 حزمة ضمن نطاق التوافق الحرج للإصدار 1.0 spine، منها 10 جاهزة للإنتاج و8 في مرحلة beta. تُشتق معلومات النضج والمجموعات من بيانات المستودع الوصفية، ويفشل أمر docs:catalog:check في حال حدوث انحراف. يتم إدارة المنهجية والخطوط المرجعية والعتبات في مجلد benchmarks/، وتعمل كبوابة حظر (blocking gate) بناءً على آخر 5 أدلة خضراء في سير العمل المخصص، لكن لا يتم عرض أرقام أداء محددة في README. كما يوضح أن جدول المقارنة مع NestJS وHono وtRPC يهدف لشرح الاختلافات التصميمية وليس لتقييم أرقام الأداء أو المنافسين.