Software Engineer Encyclopedia
0%
Practice track

المشاريع العملية

10 progressive project milestones

القراءة لوحدها مش بتعمل مهندس. كل مشروع هنا مربوط بدروس محددة، بمهام واضحة ومعيار قبول تقدر تقيس نفسك عليه. ابنيهم بالترتيب — كل مشروع بيكمّل على اللي قبله، ومفيش واحد فيهم معقّد أكتر من اللازم.

Project 01 · Beginner

Web API منظم بـ ASP.NET Core

A well-structured ASP.NET Core Web API

API لإدارة مهام (Tasks) بـ CRUD كامل، من غير قاعدة بيانات حقيقية في الأول (in-memory)، عشان تركّز على الـ pipeline والـ contracts.

المهام

  1. اعمل مشروع Web API وحدد الـ endpoints: GET/POST/PUT/DELETE /api/tasks مع pagination وfiltering.
  2. افصل الـ DTOs عن الـ domain model وضيف validation.
  3. رجّع الأخطاء بصيغة ProblemDetails من exception handler واحد.
  4. سجّل الخدمات بـ DI واختار lifetime مناسب لكل واحدة.
  5. فعّل OpenAPI وجرّب كل endpoint منه.

معيار القبول — تعتبره خلص لما

  • كل endpoint بيرجّع status code صح (201 مع Location، 404، 400 بتفاصيل الـ validation).
  • مفيش try/catch متكرر في الـ endpoints.
  • تقدر تشرح ترتيب الـ middleware عندك وليه.

الدروس المرتبطة

Project 02 · Intermediate

Backend جاهز للإنتاج: Auth + Database

Production-oriented backend with authentication, authorization and a database

كمّل على المشروع الأول: قاعدة بيانات حقيقية، مستخدمين، وصلاحيات — بحيث كل مستخدم يشوف مهامه بس.

المهام

  1. ضيف EF Core مع migrations وعلاقة User → Tasks.
  2. طبّق تسجيل/دخول بـ JWT access token + refresh token rotation.
  3. ضيف policy بتمنع المستخدم من الوصول لمهمة مش بتاعته (resource-based authorization).
  4. اكتب unit tests للـ business rules وintegration tests للـ endpoints بـ WebApplicationFactory.
  5. راجع الـ queries: مفيش N+1، وفيه index على الأعمدة اللي بتفلتر بيها.

معيار القبول — تعتبره خلص لما

  • Integration test بيثبت إن user A بياخد 403/404 على بيانات user B.
  • الـ refresh token القديم بيتلغي بعد الاستخدام، وإعادة استخدامه بتلغي السلسلة كلها.
  • الـ secrets مش في الـ repo.

الدروس المرتبطة

Project 03 · Intermediate

Caching بـ Redis ومعالجة في الخلفية

Redis caching and background processing

خلّي القراءات التقيلة سريعة والشغل الطويل يتنفذ برا الـ request — من غير ما تعرض بيانات قديمة أو تنفذ الشغل مرتين.

المهام

  1. ضيف cache-aside على endpoint قراءة تقيل، مع TTL وinvalidation عند التعديل.
  2. احمي نفسك من الـ cache stampede (lock أو HybridCache).
  3. انقل إرسال الإيميل/التقرير لـ background job بـ Hangfire أو BackgroundService.
  4. خلّي الـ job idempotent: لو اتنفذ مرتين النتيجة واحدة.
  5. ضيف rate limiting على الـ endpoints العامة.

معيار القبول — تعتبره خلص لما

  • تقدر تقيس الفرق قبل/بعد الـ cache بأرقام.
  • بعد أي تعديل، القراءة التالية بترجّع البيانات الجديدة.
  • إعادة تشغيل الـ job مش بتبعت إيميلين.

الدروس المرتبطة

Project 04 · Advanced

Modular Monolith بأحداث

A modular monolith with domain and integration events

قسّم التطبيق لـ modules بحدود واضحة (مثلاً Tasks وNotifications وBilling) بتتكلم مع بعض بأحداث، من غير ما تروح microservices.

المهام

  1. حدد الـ modules وامنع أي module يقرأ جداول التاني مباشرة.
  2. طبّق Clean Architecture جوه module واحد على الأقل، وبرّر كل layer.
  3. ابعت integration events عن طريق Outbox pattern.
  4. خلّي الـ consumers idempotent.
  5. اكتب architecture test بيفشل لو module كسر الحدود.

معيار القبول — تعتبره خلص لما

  • لو الـ consumer وقع، الحدث مش بيضيع وبيتعالج بعد ما يرجع.
  • تقدر تشرح ليه ده مش microservices وإمتى تتحول.
  • مفيش pattern موجود من غير مشكلة بيحلها.

الدروس المرتبطة

Project 05 · Advanced

نشر ومراقبة كاملين

A complete deployment and observability workflow

من git push لحد تطبيق شغال ومتراقب: container، pipeline، بيئة سحابية، وtelemetry.

المهام

  1. اكتب Dockerfile multi-stage بـ non-root user، وCompose للتطبيق + قاعدة البيانات + Redis.
  2. اعمل GitHub Actions workflow: restore → build → test → image → deploy.
  3. انشر على Azure App Service/Container Apps أو Cloud Run، والـ secrets من الـ secret store.
  4. ضيف OpenTelemetry (traces + metrics + logs) وhealth checks (liveness/readiness).
  5. اعمل failure drill: وقّف قاعدة البيانات وشوف الـ readiness والـ alerts.

معيار القبول — تعتبره خلص لما

  • أي commit على main بينزل production من غير خطوات يدوية.
  • تقدر تتبع request واحد من الـ API للـ DB في الـ traces.
  • الـ rollback خطوة واحدة موثقة.

الدروس المرتبطة

Project 06 · Intermediate

مشروع تصنيف بـ Machine Learning

A machine learning classification project

موديل بيتوقع هل التذكرة (ticket) عاجلة ولا لأ — بـ pipeline سليم وتقييم تقدر تدافع عنه.

المهام

  1. نضّف البيانات واعمل EDA سريع: القيم الناقصة، توزيع الـ classes.
  2. قسّم train/validation/test قبل أي تحويل، واعمل كل الـ preprocessing جوه Pipeline.
  3. قارن baseline (DummyClassifier) بـ Logistic Regression وGradient Boosting بـ cross-validation.
  4. اختار الـ metric حسب تكلفة الغلط (precision/recall/PR-AUC) وحدد الـ threshold.
  5. احفظ الموديل مع نسخته ونسخة البيانات والـ metrics.

معيار القبول — تعتبره خلص لما

  • الموديل أحسن من الـ baseline بفرق واضح على test set ما اتلمستش.
  • مفيش data leakage (تقدر تشرح ليه).
  • عندك confusion matrix وتفسير لأهم الأخطاء.

الدروس المرتبطة

دليل التنفيذ: المعمارية، بنية المشروع، الـ contract، الاختبارات، التشغيل، الأمان

المعمارية

  • Batch training job بيقرأ snapshot من البيانات ويطلّع model bundle (الموديل + metadata + schema + golden predictions).
  • Model registry بسيط: فولدر/‏bucket بنسخ مرقّمة و alias اسمه production.
  • Evaluation report بيتولّد مع كل تدريب ويتقارن بالنسخة الحالية (promotion gate).

بنية المشروع

TextFolder structure
churn-model/
├── pyproject.toml            # pinned dependencies
├── data/                     # snapshots, never edited in place
├── src/churn/
│   ├── features.py           # ColumnTransformer: the ONLY place preprocessing lives
│   ├── train.py              # split -> CV -> fit -> evaluate -> bundle
│   ├── evaluate.py           # metrics, slices, threshold from costs
│   ├── bundle.py             # save/load + hash + golden predictions
│   └── schema.py             # input contract
├── tests/
│   ├── test_no_leakage.py    # noise labels must score at chance
│   ├── test_schema.py
│   └── test_golden.py
└── reports/                  # one evaluation report per trained version

الـ Contract الأساسي

JSONbundle/metadata.json — the contract every later project consumes
{
  "name": "churn",
  "version": 14,
  "sha256": "…",
  "sklearn": "1.9.1",
  "training_data_sha256": "…",
  "metrics": { "pr_auc_test": 0.52, "brier": 0.11 },
  "decision_threshold": 0.07,
  "schema": { "tenure_months": { "type": "int", "min": 0, "max": 600 } },
  "golden": { "inputs": [], "expected": [] }
}

خطة الاختبار

  • Leakage test: درّب على labels عشوائية؛ الـ CV score لازم يبقى قرب الصدفة.
  • Schema test: كل حقل ناقص/زايد/برا النطاق بيترفض.
  • Golden test: تحميل الـ bundle بيدّي نفس التوقعات المسجلة.
  • Reproducibility: نفس الـ seed + نفس الـ snapshot = نفس الـ metrics.

التشغيل والمراقبة

  • التدريب job بيتشغّل يدوي أو بجدول؛ مفيش serving في المشروع ده.
  • سجّل لكل run: commit، snapshot hash، hyperparameters، metrics.

الأمان

  • البيانات فيها معلومات عملاء: ما تدخلش الـ repo، والـ snapshots في storage بصلاحيات.
  • ما تحمّلش joblib من مصدر مش موثوق.

أعطال شائعة

  • الـ preprocessing اتعمل برا الـ Pipeline ⇒ أرقام تقييم متفائلة.
  • الـ threshold اتختار على الـ test set.
  • feature بتتسجل بعد الحدث (target leakage).

الـ labs المتنفذة اللي بتبني عليها

Project 07 · Advanced

تطبيق .NET متصل بخدمة ML

A .NET application integrated with an ML inference service

شغّل موديل المشروع السادس كخدمة inference (FastAPI)، واستهلكه من الـ API بتاعك في .NET بشكل يتحمل الأعطال.

المهام

  1. اعمل خدمة Python بـ endpoint /predict بـ schema واضح وversion للموديل في الـ response.
  2. استهلكها من .NET بـ typed HttpClient مع timeout وretry وcircuit breaker.
  3. حدد سلوك الـ fallback لما الخدمة تقع.
  4. سجّل كل prediction (input hash، نسخة الموديل، latency) للمراقبة.
  5. شغّل الاتنين بـ Compose.

معيار القبول — تعتبره خلص لما

  • لما خدمة الـ ML تقع، الـ API بيرد برد واضح ومش بيعلّق.
  • تقدر تعرف أي نسخة موديل ردّت على أي request.
  • فيه contract test بين الخدمتين.

الدروس المرتبطة

دليل التنفيذ: المعمارية، بنية المشروع، الـ contract، الاختبارات، التشغيل، الأمان

المعمارية

  • ASP.NET Core API: هوية المستخدم، الصلاحيات، الـ business rules، وتسجيل كل توقع.
  • Python inference service (FastAPI) على شبكة داخلية: بيحمّل الـ bundle مرة عند الـ startup، بيتحقق من الـ golden predictions، وبيرد بالاحتمال + نسخة الموديل.
  • Typed HttpClient بـ timeout لكل محاولة، retry محدود، circuit breaker، و fallback صريح.
  • Compose بيشغّل الاتنين + قاعدة البيانات.

بنية المشروع

TextFolder structure
churn-platform/
├── docker-compose.yml
├── inference/                    # Python
│   ├── Dockerfile
│   ├── app/main.py               # /v1/predict, /health/ready
│   ├── app/schemas.py            # Pydantic request/response
│   └── tests/test_api.py         # contract + validation tests
├── api/                          # .NET
│   ├── Api/Program.cs
│   ├── Api/Prediction/PredictionClient.cs
│   ├── Api/Prediction/ChurnScoreService.cs   # fallback policy lives here
│   ├── Api/Data/PredictionLog.cs
│   └── Api.Tests/PredictionClientTests.cs    # timeouts, 422, 5xx, breaker
└── contracts/predict.v1.json     # shared JSON Schema: both sides test against it

الـ Contract الأساسي

HTTPThe contract between the two services
POST /v1/predict
Content-Type: application/json

{ "tenure_months": 3, "monthly_charge": 80.0, "support_tickets": 2, "plan": "basic" }

200 OK
{ "churn_probability": 0.71, "model_version": "churn-classifier:14" }

422 Unprocessable Entity      <- contract violation: never retried by the caller
503 Service Unavailable       <- model not loaded: retried, then circuit breaker

خطة الاختبار

  • Contract test: الـ ‎.NET DTO والـ Pydantic model بيتختبروا ضد نفس الـ JSON Schema.
  • Resilience tests بـ fake handler: timeout، 5xx متكرر (الـ breaker يفتح)، 422 (مفيش retry).
  • Fallback test: لما الخدمة واقعة الـ API بيرد 200 من غير score ومعاه علامة scoreUnavailable.
  • Parity test: نفس الـ input للـ bundle مباشرة وللخدمة بيدّي نفس الرقم.

التشغيل والمراقبة

  • Readiness للخدمة = الموديل اتحمّل والـ golden predictions عدّت.
  • Metrics: latency لكل نسخة موديل، نسبة الـ fallback، نسبة الـ 422.
  • جدول PredictionLog: input hash، النتيجة، نسخة الموديل، الوقت — ده أساس مراقبة الـ drift.

الأمان

  • خدمة الـ inference مش متاحة من الإنترنت (network policy أو mTLS).
  • الـ tenant/user بيتحددوا في الـ API بس؛ الخدمة ما بتستقبلش هوية.
  • الـ logs ما فيهاش الـ features الخام لو فيها بيانات شخصية.

أعطال شائعة

  • async def endpoint بـ inference blocking ⇒ الـ health check بيعلّق تحت الحمل.
  • اختلاف preprocessing بين التدريب والخدمة (skew).
  • Retry من غير حد إجمالي ⇒ requests معلّقة و threads بتخلص.

الـ labs المتنفذة اللي بتبني عليها

Project 08 · Professional Engineering

مساعد معرفي بـ RAG

A RAG-powered knowledge assistant

مساعد بيجاوب من مستندات شركتك بـ citations، وبيقول «معرفش» لما الإجابة مش في المصادر.

المهام

  1. اعمل ingestion: استخراج نص، chunking بـ overlap، metadata (المصدر، الصلاحيات، التاريخ).
  2. خزّن الـ embeddings في pgvector أو vector store تاني، واعمل hybrid search (vector + keyword).
  3. ضيف reranking وفلترة بالـ metadata حسب صلاحيات المستخدم.
  4. ابنِ الـ prompt بحيث الإجابة مقيدة بالمصادر ومعاها citations.
  5. اعمل golden set من 30–50 سؤال وقِس recall@k والـ faithfulness.

معيار القبول — تعتبره خلص لما

  • recall@5 متقاس ومكتوب، وأي تغيير في الـ chunking بيتقارن بيه.
  • المستخدم مش بيشوف chunk من مستند مالوش صلاحية عليه.
  • السؤال اللي برا المصادر بيترد عليه بالرفض مش بالتأليف.

الدروس المرتبطة

دليل التنفيذ: المعمارية، بنية المشروع، الـ contract، الاختبارات، التشغيل، الأمان

المعمارية

  • Ingestion worker: parse → chunk → embed → upsert، incremental بـ content hashing، وبيمسح اللي اتشال.
  • PostgreSQL + pgvector: الـ chunks والـ embeddings والـ tsvector في جدول واحد، و RLS على الـ tenant.
  • Retrieval: hybrid (vector + full-text) بـ RRF، والفلترة بالصلاحيات جوه الـ query.
  • Answer service: prompt مقيد بالمصادر، citations، وتحقق بالكود قبل الرد.
  • Evaluation: golden set + recall@k/MRR للـ retrieval + grounding checks، بيتشغّل في الـ CI.

بنية المشروع

TextFolder structure
knowledge-assistant/
├── ingestion/                  # Python worker
│   ├── parse.py  chunk.py  embed.py
│   ├── sync.py                 # incremental: hashes, deletes, pipeline version
│   └── tests/test_sync.py      # edit, cosmetic change, delete, re-run
├── api/                        # ASP.NET Core
│   ├── Retrieval/HybridSearch.cs
│   ├── Answers/AnswerService.cs    # prompt + citation verification
│   ├── Answers/PromptCatalog.cs    # versioned prompts
│   └── Api.Tests/IsolationTests.cs # tenant A never sees tenant B chunks
├── db/schema.sql               # chunks table, HNSW + GIN indexes, RLS policy
└── eval/
    ├── golden.jsonl            # question, relevant chunk ids, expected facts
    └── run_eval.py             # recall@k, MRR, citation validity -> exit code

الـ Contract الأساسي

JSONPOST /api/ask — response shape
{
  "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 افتراضيًا.

أعطال شائعة

  • تغيير الـ embedding model من غير re-embed.
  • فلترة بعد الـ top-k ⇒ نتايج فاضية أو تسريب.
  • تقييم الإجابات قبل تقييم الـ retrieval.

الـ labs المتنفذة اللي بتبني عليها

Project 09 · Professional Engineering

تطبيق AI بأدوات MCP

An MCP-enabled AI application

اعرض وظائف نظامك (بحث عن طلب، حالة تذكرة) كـ MCP tools، واستهلكها من agent بحدود وصلاحيات.

المهام

  1. ابنِ MCP server بـ C# SDK فيه 2–3 أدوات read-only بـ schemas دقيقة.
  2. اربط كل tool بـ application service بيطبق authorization المستخدم الحقيقي.
  3. استهلك الأدوات من IChatClient مع allowlist وحد أقصى لعدد الـ tool calls.
  4. ضيف tool واحدة بتعدّل بيانات، بـ human approval قبل التنفيذ وidempotency key.
  5. اكتب tests: tool args غلط، مستخدم من غير صلاحية، prompt injection جوه نتيجة tool.

معيار القبول — تعتبره خلص لما

  • الموديل مش قادر يوصل لبيانات مستخدم تاني مهما كان الـ prompt.
  • كل tool call متسجل: مين، إيه، النتيجة.
  • العملية اللي بتعدّل مش بتتنفذ من غير موافقة.

الدروس المرتبطة

دليل التنفيذ: المعمارية، بنية المشروع، الـ contract، الاختبارات، التشغيل، الأمان

المعمارية

  • MCP server (ASP.NET Core، stateless HTTP): أدوات ضيقة فوق الـ application services، بصلاحيات المستخدم الحقيقي.
  • Agent host: IChatClient + allowlist للأدوات + حد أقصى للـ tool loop + budget.
  • Approval flow: أي أداة write بتتحول لطلب موافقة متخزن، والـ run بيكمّل بعد القرار.
  • Run store: كل خطوة ونتيجتها متسجلين (durable) عشان الـ resume والـ audit.

بنية المشروع

TextFolder structure
support-agent/
├── McpServer/
│   ├── Program.cs                # AddMcpServer().WithHttpTransport().WithToolsFromAssembly()
│   ├── Tools/OrderTools.cs       # read tools
│   ├── Tools/RefundTools.cs      # write tool: idempotency key required
│   └── McpServer.Tests/          # 401, cross-user access, schema violations
├── AgentHost/
│   ├── Runs/RunStore.cs          # runs, steps, pending approvals
│   ├── Runs/AgentRunner.cs       # the loop: allowlist, budget, approval, checkpoint
│   ├── Policies/ToolPolicy.cs    # risk level per tool
│   └── AgentHost.Tests/TrajectoryTests.cs
└── eval/scenarios.jsonl          # task, allowed tools, expected end state, forbidden calls

الـ Contract الأساسي

JSONA stored step — the unit of audit and of resume
{
  "runId": "run-42",
  "step": 3,
  "tool": "refund_order",
  "arguments": { "orderId": "…", "amount": 120, "idempotencyKey": "run-42:3" },
  "risk": "write",
  "approval": { "status": "approved", "by": "agent.lead@…", "at": "2026-11-14T08:12:00Z" },
  "result": { "refunded": 120 },
  "tokens": { "input": 1840, "output": 62 }
}

خطة الاختبار

  • مستخدم A ما يقدرش يوصل لطلب مستخدم B عن طريق أي أداة.
  • Write من غير approval ما بيتنفذش؛ الرفض بيرجع للموديل كنتيجة.
  • Retry بنفس الـ idempotency key ما بيكررش الأثر.
  • Crash بعد خطوة: الـ resume ما بيعيدش الخطوات المسجلة.
  • Scenario eval على موديل حقيقي: نسبة نجاح ≥ الحد على N تشغيل، وصفر نداءات ممنوعة.

التشغيل والمراقبة

  • Metric لكل run: عدد الخطوات، الـ tokens، هل احتاج موافقة، النتيجة.
  • Alert على الـ runs اللي وصلت للحد الأقصى للخطوات (علامة loop).

الأمان

  • الأسرار في الـ backend مش في الـ prompt.
  • نتايج الأدوات بيانات مش تعليمات؛ الدفاع الحقيقي هو الصلاحيات والموافقة.
  • ثبّت نسخ أي MCP server خارجي وراجع تغيّر أوصاف أدواته.

أعطال شائعة

  • أداة عامة (run_sql) بدل أدوات business ضيقة.
  • الهوية جاية في الـ arguments.
  • Mutation من غير idempotency مع transport بيعيد الطلبات.

الـ labs المتنفذة اللي بتبني عليها

Project 10 · Intermediate

مخزن Offline-First بـ SQLite (مشروع دومين)

Offline-first inventory with SQLite and EF Core

تطبيق مخزون بيشتغل من غير إنترنت: STRICT tables، transactions ذرية، optimistic concurrency، outbox للمزامنة، وbackup/restore متحقق منه. الكود في EXAMPLES/InventoryOffline.

المهام

  1. شغّل اختبارات النسخة المرجعية: cd EXAMPLES/InventoryOffline/python-reference && python -m unittest -v (11 اختبار).
  2. اقرأ sql/schema.sql واشرح كل constraint ليه موجود.
  3. نفّذ نسخة .NET: dotnet new sln ثم أضف المشروعين وشغّل dotnet test (لم تُنفَّذ في بيئة البناء).
  4. أضف FTS5 للبحث النصي واختبره.
  5. اكتب sync server بسيط يتجاهل change_id المكرر.

معيار القبول — تعتبره خلص لما

  • كل الاختبارات خضراء ومعاك دليل للـ backup/restore.
  • تقدر تشرح ليه الـ outbox بيتكتب في نفس transaction التعديل.
  • تقدر تحدد سياسة الـ conflicts وتبررها.

الدروس المرتبطة

Project 11 · Intermediate

ستة أنظمة AI صغيرة متختبرة (مشروع دومين)

Six tested AI mini-systems

ML API ومقارنة نماذج وRAG بصلاحيات وAgent بموافقة بشرية وEvaluation gate وMLOps registry/drift/canary. الكود في EXAMPLES/AI-Projects وبيشتغل offline.

المهام

  1. شغّل ./run_all.sh وتأكد من 19 اختبار.
  2. غيّر size/overlap في RAG وقِس الأثر بـ run_eval.
  3. أضف /predict_batch بحد أقصى للصفوف.
  4. اربط RAG بـ endpoint /ask مع tenant isolation.
  5. استبدل الـ stub planner/generator بنموذج حقيقي (يحتاج credentials).

معيار القبول — تعتبره خلص لما

  • كل الاختبارات خضراء.
  • تقدر تشرح ليه الفلترة قبل الـ ranking وليه الـ agent guardrails في الكود.
  • عندك golden set وregression gate في CI.

الدروس المرتبطة

Project 12 · Advanced

تصميم E-commerce (System Design) مع core متختبر

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.

المهام

  1. اقرأ README.md واعترض على افتراضات الـ capacity بأرقامك.
  2. شغّل python -m unittest -v (7 اختبارات).
  3. أضف طبقة HTTP بـ endpoint POST /orders مع Idempotency-Key.
  4. ضيف Redis بدل TTLCache وقِس.
  5. اكتب load test وسجّل أرقام حقيقية.

معيار القبول — تعتبره خلص لما

  • اختبار الـ concurrency أخضر.
  • تقدر تشرح ليه UPDATE ... WHERE stock>=? ذري.
  • تقدر تحدد bottleneck بالقياس مش بالتخمين.

الدروس المرتبطة

Project 13 · Beginner

مشروع كبير 1: Console Expense Tracker بـ C#

Major Project 1 — C# console expense tracker

أساسيات C#: records وinterfaces وLINQ وملفات JSON وأخطاء واختبارات. الكود في EXAMPLES/MajorProjects/P1-Console-ExpenseTracker (Not Executed: مفيش .NET SDK وقت التأليف).

المهام

  1. شغّل dotnet test وصلّح أي خطأ compile.
  2. أضف أمر export csv.
  3. أضف ميزانية شهرية وتنبيه.
  4. اكتب اختبار لحالة الملف التالف.

معيار القبول — تعتبره خلص لما

  • الاختبارات خضراء.
  • تقدر تشرح ليه المبالغ long cents.
  • تقدر تشرح فايدة IExpenseRepository.

الدروس المرتبطة

Project 14 · Intermediate

مشروع كبير 2: CRUD Web API

Major Project 2 — CRUD Web API (Library)

Controllers وDTOs وvalidation وEF Core وعلاقة 1-N وpagination/filter/sort واختبارات integration. الكود في EXAMPLES/MajorProjects/P2-CrudApi-Library (Not Executed).

المهام

  1. شغّل الاختبارات واقرأ كل 400/409.
  2. اعمل migration حقيقية بدل EnsureCreated.
  3. أضف ETag أو concurrency token للنسخ المتاحة.
  4. أضف versioning للـ API.

معيار القبول — تعتبره خلص لما

  • كل endpoint ليه اختبار نجاح وفشل.
  • تقدر تشرح ليه الـ sort من allow-list.

الدروس المرتبطة

Project 15 · Intermediate

مشروع كبير 3: Secure API

Major Project 3 — Secure API (JWT, refresh rotation, roles)

يوسّع المشروع 2: PBKDF2 وJWT وrefresh rotation مع reuse detection وroles/policies واختبارات authorization. الكود في EXAMPLES/MajorProjects/P3-SecureApi-Library (Not Executed).

المهام

  1. شغّل SecurityTests وافهم ليه reuse بيقتل الـ family.
  2. أضف rate limiting على /api/auth/*.
  3. أضف account lockout.
  4. اكتب threat model صفحة واحدة.

معيار القبول — تعتبره خلص لما

  • تقدر تشرح 401 مقابل 403.
  • تقدر تشرح ليه الـ refresh بيتخزن hash.

الدروس المرتبطة

Project 16 · Advanced

مشروع كبير 4: Angular Full-Stack

Major Project 4 — Angular full-stack dashboard

Angular وRxJS وsignals وguards وinterceptor مع single-flight refresh فوق P3. منطق الـ auth اتختبر (tsc + 5 اختبارات)، وكود Angular Not Executed. في EXAMPLES/MajorProjects/P4-Angular-FullStack.

المهام

  1. شغّل setup.sh وng serve.
  2. اكتب اختبار interceptor للـ 401 → refresh → retry.
  3. انقل الـ refresh token لـ HttpOnly cookie مع CSRF.
  4. أضف e2e بـ Playwright.

معيار القبول — تعتبره خلص لما

  • الصفحات بتشتغل مع API P3.
  • تقدر تشرح ليه guards مش أمان.

الدروس المرتبطة

Project 17 · Advanced

مشروع كبير 5: Production Deployment

Major Project 5 — Docker, CI/CD and deployment runbook

Compose وnginx وhealth checks وإعداد البيئة وCI/CD وrollback وbackup. في EXAMPLES/MajorProjects/P5-Production-Deployment (YAML اتحلل، الباقي Not Executed).

المهام

  1. شغّل docker compose up وsmoke.sh.
  2. اعمل rollback لـ image قديم.
  3. جرّب backup/restore للـ volume.
  4. أضف structured logging.

معيار القبول — تعتبره خلص لما

  • smoke test بيعدي.
  • تقدر تشرح expand/migrate/contract.

الدروس المرتبطة

Project 18 · Professional Engineering

مشروع التخرج: 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/ للمقارنة.

المهام

  1. اقرأ CAPSTONE/README.md وشغّل docker compose up --build (من غير أي AI key).
  2. نفّذ الـ 7 milestones بالترتيب من الدرس 14/11، وكل milestone لازم تتعرض كـ demo.
  3. شغّل python evals/run.py وevals/gate.py وevals/security/run_security.py، وبعدين خرّب دفاع واحد وتأكد إن الـ suite بيفشل.
  4. وصّل موديل حقيقي (provider أو vLLM/Ollama) وشغّل نفس الـ eval بـ --api.
  5. أضف ADR لأي تقنية جديدة بأرقام قبل/بعد.

معيار القبول — تعتبره خلص لما

  • Tenant A مش بيشوف بيانات tenant B في الـ API والـ retrieval والـ cache، ومثبت باختبار وsabotage.
  • الـ eval gate والـ security suite بيوقفوا الـ CI فعلًا.
  • كل قرار كبير عليه ADR، وفيه RFC وpostmortem drill وتقرير eval/تكلفة/latency صريح بالحدود.
  • تقدر تدافع عن المشروع في إنترفيو Senior/Staff بالأسئلة اللي في الدرس 14/11.

الدروس المرتبطة

دليل التنفيذ: المعمارية، بنية المشروع، الـ contract، الاختبارات، التشغيل، الأمان

المعمارية

  • بيجمع المشاريع 7 و8 و9 تحت multi-tenancy: كل جدول فيه tenant_id وعليه RLS.
  • Model gateway: routing بين موديل صغير وكبير، fallback، و budget لكل tenant قبل النداء.
  • Usage metering: كل نداء موديل بيتسجل (tenant، feature، tokens، تكلفة) وبيتجمّع للفوترة والـ quotas.
  • Background jobs: الـ ingestion والتقارير عن طريق queue + outbox، بـ consumers idempotent.
  • Release pipeline: eval gate للـ prompts/الموديلات، feature flags للـ rollout، canary ثم تعميم.

بنية المشروع

TextFolder structure
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
CREATE TABLE usage_events (
    id            uuid PRIMARY KEY,            -- idempotency: the same model call is recorded once
    tenant_id     uuid        NOT NULL,
    feature       text        NOT NULL,        -- 'ask', 'triage', 'agent'
    model         text        NOT NULL,
    prompt_version text       NOT NULL,
    input_tokens  int         NOT NULL,
    output_tokens int         NOT NULL,
    cost_micros   bigint      NOT NULL,        -- integer money: never float
    occurred_at   timestamptz NOT NULL
);
CREATE INDEX usage_tenant_period ON usage_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 قديمة ما اتشالتش ⇒ مسارات كود محدش بيختبرها.

الـ labs المتنفذة اللي بتبني عليها