القراءة لوحدها مش بتعمل مهندس. كل مشروع هنا مربوط بدروس محددة، بمهام واضحة ومعيار قبول تقدر تقيس نفسك عليه. ابنيهم بالترتيب — كل مشروع بيكمّل على اللي قبله، ومفيش واحد فيهم معقّد أكتر من اللازم.
Project 01 · Beginner
Web API منظم بـ ASP.NET Core
A well-structured ASP.NET Core Web API
API لإدارة مهام (Tasks) بـ CRUD كامل، من غير قاعدة بيانات حقيقية في الأول (in-memory)، عشان تركّز على الـ pipeline والـ contracts.
المهام
اعمل مشروع Web API وحدد الـ endpoints: GET/POST/PUT/DELETE /api/tasks مع pagination وfiltering.
افصل الـ DTOs عن الـ domain model وضيف validation.
رجّع الأخطاء بصيغة ProblemDetails من exception handler واحد.
سجّل الخدمات بـ DI واختار lifetime مناسب لكل واحدة.
فعّل OpenAPI وجرّب كل endpoint منه.
معيار القبول — تعتبره خلص لما
كل endpoint بيرجّع status code صح (201 مع Location، 404، 400 بتفاصيل الـ validation).
دليل التنفيذ: المعمارية، بنية المشروع، الـ contract، الاختبارات، التشغيل، الأمان
المعمارية
ASP.NET Core API: هوية المستخدم، الصلاحيات، الـ business rules، وتسجيل كل توقع.
Python inference service (FastAPI) على شبكة داخلية: بيحمّل الـ bundle مرة عند الـ startup، بيتحقق من الـ golden predictions، وبيرد بالاحتمال + نسخة الموديل.
Typed HttpClient بـ timeout لكل محاولة، retry محدود، circuit breaker، و fallback صريح.
{"answer":"Refunds are processed within 3 business days [1].","citations":[{"n":1,"documentId":"returns","headingPath":"Returns > Refund timing","chunkId":"returns:9f2c…"}],"abstained":false,"trace":{"promptVersion":"answer-v8","model":"…","retrieved":5,"inputTokens":2310,"outputTokens":41}}
خطة الاختبار
Sync tests: إعادة التشغيل = صفر embeddings؛ الحذف بيشيل الـ chunks.
Isolation test بـ raw SQL من غير WHERE بهوية tenant A.
Retrieval eval: recall@5 ≥ الحد المتفق عليه، وبيفشل الـ CI لو نزل.
Grounding: كل citation بيشاور على chunk اترجّع فعلًا؛ سؤال برا المصادر ⇒ abstained: true.
Injection test: مستند فيه تعليمات ما بيغيّرش سلوك الإجابة ولا بينادي أدوات.
التشغيل والمراقبة
Spans: retrieve / rerank / generate، بـ tenant و prompt version و tokens.
Dashboards: recall على عيّنة دورية، نسبة الـ abstain، التكلفة لكل tenant، p95 لكل مرحلة.
إعادة فهرسة كاملة عند تغيير الـ chunker أو الـ embedding model (index جديد ثم تبديل).
الأمان
صلاحيات المستند بتتخزن مع كل chunk وبتتطبق قبل الترتيب.
الحذف بيوصل للـ index ولأي cache إجابات.
نص الـ prompts والردود ما بيتسجلش في الـ telemetry افتراضيًا.
تطبيق مخزون بيشتغل من غير إنترنت: STRICT tables، transactions ذرية، optimistic concurrency، outbox للمزامنة، وbackup/restore متحقق منه. الكود في EXAMPLES/InventoryOffline.
المهام
شغّل اختبارات النسخة المرجعية: cd EXAMPLES/InventoryOffline/python-reference && python -m unittest -v (11 اختبار).
اقرأ sql/schema.sql واشرح كل constraint ليه موجود.
نفّذ نسخة .NET: dotnet new sln ثم أضف المشروعين وشغّل dotnet test (لم تُنفَّذ في بيئة البناء).
أضف FTS5 للبحث النصي واختبره.
اكتب sync server بسيط يتجاهل change_id المكرر.
معيار القبول — تعتبره خلص لما
كل الاختبارات خضراء ومعاك دليل للـ backup/restore.
تقدر تشرح ليه الـ outbox بيتكتب في نفس transaction التعديل.
E-commerce system design with a tested checkout core
معمارية e-commerce كاملة على الورق (requirements، capacity، API، schema، failure scenarios) مع تنفيذ فعلي لقلب الـ checkout: منع overselling وidempotency وcache-aside وoutbox. الكود في EXAMPLES/Ecommerce-SystemDesign.
المهام
اقرأ README.md واعترض على افتراضات الـ capacity بأرقامك.
شغّل python -m unittest -v (7 اختبارات).
أضف طبقة HTTP بـ endpoint POST /orders مع Idempotency-Key.
Angular وRxJS وsignals وguards وinterceptor مع single-flight refresh فوق P3. منطق الـ auth اتختبر (tsc + 5 اختبارات)، وكود Angular Not Executed. في EXAMPLES/MajorProjects/P4-Angular-FullStack.
مشروع التخرج: Enterprise AI Knowledge Assistant كـ SaaS متعدد المستأجرين
Master Capstone — Enterprise AI Knowledge Assistant (multi-tenant SaaS)
بيوحّد «AI SaaS متعدد المستأجرين» و«المشروع الكبير 6» في منتج واحد: ASP.NET Core modular monolith، PostgreSQL + pgvector بـ RLS، Python ingestion، LLM gateway بـ budgets وfallback، MCP بموافقة بشرية، eval gate وsecurity suite في CI، Angular عربي/إنجليزي، Docker وGitHub Actions وBicep. الكود في CAPSTONE/ ودليل البناء في الدرس 14/11. متحقق: build الـ backend و12/12 اختبار (.NET 9 SDK)، 8/8 اختبارات Python، الـ eval gate والـ security suite. النسخة الأولية P6 لسه في EXAMPLES/ للمقارنة.
المهام
اقرأ CAPSTONE/README.md وشغّل docker compose up --build (من غير أي AI key).
نفّذ الـ 7 milestones بالترتيب من الدرس 14/11، وكل milestone لازم تتعرض كـ demo.
شغّل python evals/run.py وevals/gate.py وevals/security/run_security.py، وبعدين خرّب دفاع واحد وتأكد إن الـ suite بيفشل.
وصّل موديل حقيقي (provider أو vLLM/Ollama) وشغّل نفس الـ eval بـ --api.
أضف ADR لأي تقنية جديدة بأرقام قبل/بعد.
معيار القبول — تعتبره خلص لما
Tenant A مش بيشوف بيانات tenant B في الـ API والـ retrieval والـ cache، ومثبت باختبار وsabotage.
الـ eval gate والـ security suite بيوقفوا الـ CI فعلًا.
كل قرار كبير عليه ADR، وفيه RFC وpostmortem drill وتقرير eval/تكلفة/latency صريح بالحدود.
تقدر تدافع عن المشروع في إنترفيو Senior/Staff بالأسئلة اللي في الدرس 14/11.
ai-saas/
├── src/
│ ├── Api/ # ASP.NET Core: auth, tenants, plans, endpoints
│ ├── Application/ # use cases, policies, quotas
│ ├── Infrastructure/
│ │ ├── Persistence/ # EF Core, RLS interceptor, outbox
│ │ ├── Ai/ModelGateway.cs # routing, fallback, budget, usage records
│ │ └── Messaging/ # relay + idempotent consumers
│ └── Workers/ # ingestion, usage aggregation
├── services/inference/ # Python (optional: reranker / classifier)
├── db/ # migrations + RLS policies
├── eval/ # golden sets + gates run in CI
├── deploy/ # compose for dev, IaC for cloud
└── tests/
├── Isolation/ # cross-tenant: API, raw SQL, retrieval
├── Quotas/ # 429 at the limit, reset on period change
└── Resilience/ # provider down, queue redelivery
الـ Contract الأساسي
SQLusage_events — the table billing, quotas and cost dashboards all read
CREATETABLEusage_events(iduuidPRIMARYKEY,-- idempotency: the same model call is recorded once
tenant_iduuidNOTNULL,featuretextNOTNULL,-- 'ask', 'triage', 'agent'
modeltextNOTNULL,prompt_versiontextNOTNULL,input_tokensintNOTNULL,output_tokensintNOTNULL,cost_microsbigintNOTNULL,-- integer money: never float
occurred_attimestamptzNOTNULL);CREATEINDEXusage_tenant_periodONusage_events(tenant_id,occurred_at);
خطة الاختبار
Isolation على 3 مستويات: الـ API، raw SQL، والـ retrieval.
Quota: الطلب اللي بيعدّي الحد بياخد 429 قبل نداء الموديل.
Outbox/consumer: إعادة التسليم ما بتكررش الأثر.
Eval gate: تغيير prompt بيكسر حالة ⇒ الـ pipeline يفشل.
Failure drill: المزوّد الأساسي واقع ⇒ fallback، والـ SLO متراقب.
التشغيل والمراقبة
Dashboards: تكلفة وجودة و latency لكل tenant ولكل feature.
SLO + error budget، و alert على عمر أقدم صف في الـ outbox.
Rollback: prompt/model alias + feature flag، من غير deploy.
الأمان
الـ API بيتصل بـ role مش صاحب الجداول؛ الـ tenant بيتحدد من الـ token وبيتحط بـ SET LOCAL.
Audit log للعمليات الحساسة وقرارات الموافقة.
PII: redaction قبل الـ telemetry، و retention محدد.
أعطال شائعة
SET من غير LOCAL مع connection pooling.
تسجيل الاستهلاك بعد الرد (بيضيع عند الـ crash) بدل ما يكون في نفس مسار النداء.
فلوس بـ float.
Flags قديمة ما اتشالتش ⇒ مسارات كود محدش بيختبرها.