Everything you need to explain AlgoLab

كل اللي محتاجه عشان تشرح AlgoLab

Read this once from top to bottom, then use the "Say it like this" boxes when you present. Every number on this page comes from the project's own code, docs and live API.

اقرا الصفحة دي مرة من الأول للآخر، وبعدين استخدم مربعات «قولها كده» وانت بتعرض. كل رقم هنا جاي من كود المشروع نفسه والدوكس والـ API.

The problem it solves

بيحل مشكلة إيه

On paper, Bubble Sort and Insertion Sort are both O(n²). In practice they do very different amounts of work on the same input, and a student rarely gets to see that. Big-O describes how cost grows; it does not show what the algorithm actually does. AlgoLab shows the exact operations and measures them on real data.

على الورق، Bubble Sort و Insertion Sort الاتنين O(n²). بس في الحقيقة بيعملوا كمية شغل مختلفة جدًا على نفس الـ input، والطالب نادرًا لما يشوف ده. الـ Big-O بيوصف التكلفة بتكبر إزاي، لكن مش بيوريك الخوارزمية بتعمل إيه بالظبط. AlgoLab بيوريك العمليات بالظبط وبيقيسها على داتا حقيقية.

The two-minute version

النسخة اللي في دقيقتين

• Frontend: React 19 + TypeScript, built with Vite. It never imports backend code; it talks to the API over HTTP with types generated from the API's OpenAPI schema.
• Backend: Python FastAPI, organised in layers (presentation, application, domain, algorithms, infrastructure). Heavy work runs in a separate worker process, one job at a time.
• Algorithms: ten sorting algorithms written so that every comparison, swap and write goes through one shared object. That object counts operations and, when asked, records a trace.
• Trust: every result is checked against Python's sorted(), every algorithm gets its own copy of the input, and timings use warm-ups and repeated runs.
• Shipping: Docker Compose locally, Azure Container Apps in the cloud, GitHub Actions for CI/CD, 558 backend tests.

• الفرونت إند: React 19 مع TypeScript، معمول بـ Vite. عمره ما بيستورد كود من الباك إند؛ بيكلم الـ API عن طريق HTTP، والـ types بتاعته متولّدة من الـ OpenAPI schema بتاعة الـ API.
• الباك إند: Python بـ FastAPI، متقسم طبقات (presentation و application و domain و algorithms و infrastructure). الشغل التقيل بيتعمل في process منفصلة (worker)، job واحدة في المرة.
• الخوارزميات: عشر خوارزميات ترتيب، مكتوبة بحيث إن كل مقارنة وكل تبديل وكل كتابة بتعدّي على object واحد مشترك. الـ object ده بيعد العمليات، ولو طلبنا منه بيسجّل trace.
• الثقة في النتايج: كل نتيجة بتتراجع على sorted() بتاعة Python، وكل خوارزمية بتاخد نسخة لوحدها من الـ input، والتوقيت بيتقاس بعد warm-up وبتشغيل متكرر.
• التشغيل والنشر: Docker Compose على الجهاز، Azure Container Apps على الكلاود، GitHub Actions للـ CI/CD، و 558 test للباك إند.

What is on the screen

إيه اللي على الشاشة

One page, three sections. They share the same algorithm selection: pick algorithms once and Race, Benchmark and Suite all use them.

صفحة واحدة فيها تلات أجزاء. التلاتة بيستخدموا نفس اختيار الخوارزميات: بتختار مرة واحدة، والـ Race والـ Benchmark والـ Suite كلهم بيشتغلوا على نفس الاختيار.

Race controls

أزرار الـ Race

• Dataset: size, min, max, pattern and seed. The same seed gives the same array every time.
• Playback: Play/Pause (Space), step back and forward (← →), Reset (R or Home), jump to end (End), a scrub bar, and speeds from 1 to 250 steps per second.
• Colours: compare, swap, write, sorted.
• Each lane shows live counts (comparisons, swaps, array writes) against the total, plus best/average/worst, space, stable and in-place.

• الداتا: الحجم والحد الأدنى والأقصى والنمط (pattern) والـ seed. نفس الـ seed بيطلّع نفس المصفوفة كل مرة.
• التشغيل: تشغيل/إيقاف (Space)، خطوة لورا وخطوة لقدام (← →)، Reset (R أو Home)، القفز للآخر (End)، شريط scrub، وسرعات من 1 لحد 250 خطوة في الثانية.
• الألوان: compare مقارنة، swap تبديل، write كتابة، sorted اترتب.
• كل lane بيعرض العدادات لحظة بلحظة (المقارنات والتبديلات والكتابات) قصاد الإجمالي، ومعاهم best و average و worst والـ space، وهل هي stable و in-place.

The tabs Searching, Graphs, Dynamic Programming, Backtracking in the top bar are placeholders for future work. Only Sorting works today. Say this clearly if asked.

التابات اللي فوق Searching و Graphs و Dynamic Programming و Backtracking مكان محجوز لشغل جاي. اللي شغال النهارده Sorting بس. قول ده بوضوح لو حد سأل.

Concepts to know

مفاهيم لازم تعرفها

Big-O, and best / average / worst case

الـ Big-O، وأحسن ومتوسط وأسوأ حالة

Big-O describes how the number of operations grows with the input size n. O(n) doubles when n doubles. O(n²) roughly quadruples. O(n log n) grows a little more than double. Best, average and worst case describe different inputs: Insertion Sort is O(n) on already-sorted data but O(n²) on reversed data.

الـ Big-O بيوصف عدد العمليات بيزيد إزاي مع حجم الـ input اللي بنسميه n. الـ O(n) بيتضاعف لما n تتضاعف. الـ O(n²) بيتضرب في 4 تقريبًا. الـ O(n log n) بيزيد أكتر من الضعف بشوية. وأحسن ومتوسط وأسوأ حالة معناهم أنواع input مختلفة: Insertion Sort بيبقى O(n) على داتا مترتبة أصلًا، لكنه O(n²) على داتا معكوسة.

Space, stable, in place, comparison-based

الـ Space والـ Stable والـ In place والـ Comparison-based

• Auxiliary space: extra memory beyond the array. O(1) means a few variables only.
• Stable: equal values keep their original order. Example: two students with grade 90; a stable sort keeps whoever came first still first. Matters when you sort records by one field after another.
• In place: sorts inside the same array instead of building a new one.
• Comparison-based: decides order only by comparing two values. Any comparison sort needs at least about n log n comparisons in the worst case. Frequency Sort is not comparison-based, which is how it can be O(n + k).

• الـ Auxiliary space: الذاكرة الزيادة غير المصفوفة نفسها. O(1) معناها شوية متغيرات بس.
• Stable (مستقرة): القيم المتساوية بتفضل بنفس ترتيبها الأصلي. مثال: طالبين جابوا 90؛ الترتيب المستقر بيخلّي اللي كان الأول يفضل الأول. ده مهم لما ترتب records بحقل وبعدين بحقل تاني.
• In place (في نفس المكان): بترتب جوه نفس المصفوفة من غير ما تبني واحدة جديدة.
• Comparison-based: بتحدد الترتيب بمقارنة قيمتين ببعض بس. أي خوارزمية بالمقارنة محتاجة على الأقل حوالي n log n مقارنة في أسوأ حالة. Frequency Sort مش بالمقارنة، وعشان كده تقدر تبقى O(n + k).

The four things AlgoLab counts

الأربع حاجات اللي AlgoLab بيعدّها

What a trace is

يعني إيه trace

A trace is the complete, ordered list of operations an algorithm performed. Each event has a sequence number, a kind (compare, swap or write), the indices, and the values. Replaying the swap and write events on the original array must rebuild the sorted result exactly. The Race is just a replay of these traces.

الـ trace هو الليستة الكاملة المترتبة لكل العمليات اللي الخوارزمية عملتها. كل event فيه رقم تسلسل، ونوع (compare أو swap أو write)، والـ indices، والقيم. لو أعدنا تنفيذ أحداث الـ swap والـ write على المصفوفة الأصلية، لازم يطلع الناتج المترتب بالظبط. الـ Race ما هوش غير replay للـ traces دي.

Real output from POST /api/v1/sort for Bubble Sort on [5, 2, 4, 1]: 11 events, 6 comparisons, 5 swaps, 10 array writes.

ده ناتج حقيقي من POST /api/v1/sort لـ Bubble Sort على [5, 2, 4, 1]: 11 event، و 6 مقارنات، و 5 تبديلات، و 10 كتابات.

Watch them sort

شوف الترتيب بعينك

This small player runs the same logic as the project's Python implementations, on ten values. Pick an algorithm, then press Play or step through it. Read the algorithm's card in the next section while it runs.

المشغّل الصغير ده بيشغّل نفس منطق الكود اللي في المشروع بالـ Python، على عشر قيم. اختار خوارزمية واضغط Play أو امشي خطوة خطوة. واقرا الكارت بتاعها في الجزء اللي بعده وهي شغالة.

Try Insertion Sort: you will see writes (shifts) and zero swaps. Try Frequency Sort: comparisons only to find the min and max, then pure writes.

جرّب Insertion Sort: هتلاقي كتابات (زق للقيم) وصفر تبديلات. وجرّب Frequency Sort: مقارنات بس عشان يلاقي أصغر وأكبر قيمة، وبعد كده كتابات بس.

The ten algorithms

الخوارزميات العشرة

Grouped by how their work grows. Open a card for the steps, the detail of our implementation, and what to say about it.

متقسمين حسب الشغل بيكبر إزاي. افتح أي كارت عشان تشوف الخطوات، وتفاصيل الـ implementation بتاعتنا، وتقول إيه عنها.

* No average bound is claimed for the halving-gap sequence. ** Only with many equal values; with distinct values the best case is O(n log n). *** When all values are equal, thanks to three-way partitioning. k = max − min + 1.

* مفيش حد متوسط معروف لتسلسل الـ gaps اللي بيتقسم على 2. ** بس لما يبقى فيه قيم كتير متساوية؛ لو القيم كلها مختلفة أحسن حالة O(n log n). *** لما كل القيم تبقى متساوية، بسبب التقسيم لتلات أجزاء. k = أكبر قيمة − أصغر قيمة + 1.

Simple quadratic sorts · O(n²)

خوارزميات بسيطة تربيعية · O(n²)

Faster than quadratic

أسرع من التربيعي

No comparisons between values · linear

من غير مقارنة بين القيم · خطية

How it works inside

بيشتغل إزاي من جوه

The layers, in plain words

الطبقات بكلام بسيط

• Presentation receives HTTP requests, validates them with schemas, and turns errors into one JSON shape: {"error": {"code", "message"}}.
• Application holds the use cases: make a dataset, sort, benchmark, run a suite. It checks the limits before any work starts.
• Domain holds the rules and contracts, with no framework imports. SortContext lives here.
• Algorithms are pure functions registered by a stable id like quick_sort. They never read clocks, make data, or touch HTTP.
• Infrastructure runs the work in a separate process and provides the clock.

• Presentation بتستقبل طلبات الـ HTTP، وتتأكد منها بالـ schemas، وتحوّل أي error لشكل JSON واحد: {"error": {"code", "message"}}.
• Application فيها الـ use cases: اعمل داتا، رتّب، اعمل benchmark، شغّل suite. وبتراجع الحدود قبل ما أي شغل يبدأ.
• Domain فيها القواعد والعقود (contracts)، ومن غير أي framework. الـ SortContext موجود هنا.
• Algorithms دوال صافية (pure) متسجلة بـ id ثابت زي quick_sort. عمرها ما بتقرا ساعة ولا بتعمل داتا ولا بتلمس HTTP.
• Infrastructure بتشغّل الشغل في process منفصلة وبتوفّر الساعة (clock).

Why layers? Dependencies point inward, so the core rules do not depend on FastAPI. You can test algorithms without a server, and add a new algorithm without touching the HTTP code.

ليه طبقات؟ الاعتماديات بتشاور لجوه، فالقواعد الأساسية مش معتمدة على FastAPI. تقدر تعمل test للخوارزميات من غير سيرفر، وتضيف خوارزمية جديدة من غير ما تلمس كود الـ HTTP.

SortContext: the one object every algorithm uses

SortContext: الـ object الوحيد اللي كل خوارزمية بتستخدمه

Algorithms never write values[i], values[j] = … directly. They call context.compare(), context.swap(), context.write() and context.auxiliary_write(). The context does the real operation and, depending on switches, counts it and records it as an event. The same algorithm code runs in three modes: counting on (metrics), tracing on (Race), or both off (timing).

الخوارزميات عمرها ما بتكتب values[i], values[j] = … بنفسها. بتنادي context.compare() و context.swap() و context.write() و context.auxiliary_write(). الـ context بيعمل العملية الحقيقية، وحسب الإعدادات بيعدّها وبيسجّلها كـ event. نفس كود الخوارزمية بيشتغل بتلات طرق: العدّ شغال (للأرقام)، أو التسجيل شغال (للـ Race)، أو الاتنين مقفولين (للتوقيت).

What happens when you press Start race

إيه اللي بيحصل لما تدوس Start race

1. The browser sends POST /api/v1/sort with the array, the algorithm ids and trace: true.
2. FastAPI validates the body (types, sizes, at most 128 values for a trace) and hands the job to the worker queue. If 4 requests are already waiting it answers 503 execution_busy.
3. The worker process gives each algorithm its own copy of the array and runs it with tracing on.
4. Each result is checked against Python's sorted(). A wrong answer stops the experiment with an error.
5. The response returns, for each algorithm, the output, the metrics and the full list of events.
6. The browser builds a Replay per algorithm. A timer moves one shared cursor forward at the chosen speed, and each lane draws the array at that step. The shortest trace finishes first.

1. المتصفح بيبعت POST /api/v1/sort فيه المصفوفة و ids الخوارزميات و trace: true.
2. FastAPI بيتأكد من الطلب (الأنواع، والأحجام، وإن الـ trace مش أكتر من 128 قيمة) وبيدّي الشغل لطابور الـ worker. لو فيه 4 طلبات مستنية أصلًا، بيرد بـ 503 execution_busy.
3. الـ worker process بيدّي كل خوارزمية نسخة لوحدها من المصفوفة وبيشغّلها والتسجيل شغال.
4. كل نتيجة بتتراجع على sorted() بتاعة Python. لو فيه إجابة غلط، التجربة بتقف بـ error.
5. الرد بيرجع لكل خوارزمية: الناتج، والأرقام، والليستة الكاملة للـ events.
6. المتصفح بيبني Replay لكل خوارزمية. فيه timer بيحرّك cursor واحد مشترك لقدام بالسرعة اللي اخترتها، وكل lane بترسم المصفوفة عند الخطوة دي. الـ trace الأقصر بيخلص الأول.

The replay engine (frontend)

محرك الـ replay (في الفرونت)

Stepping backward or dragging the scrub bar needs no new request. The engine saves a snapshot of the bars every 256 events (a checkpoint). To show step 1,000 it starts from the checkpoint at 768 and replays only the events after it. Bars keep a stable id, so a value can animate to its new position when it moves.

الرجوع خطوة لورا أو سحب شريط الـ scrub مش محتاج request جديد. المحرك بيحفظ صورة من الأعمدة كل 256 event (بنسميها checkpoint). عشان يعرض الخطوة 1,000، بيبدأ من الـ checkpoint اللي عند 768 ويعيد الـ events اللي بعدها بس. وكل عمود ليه id ثابت، فالقيمة تقدر تتحرك بأنيميشن لمكانها الجديد لما تتنقل.

Why a separate worker process?

ليه process منفصلة للـ worker؟

Sorting is CPU work. Running it in the web process would block other requests, and two benchmarks running together would slow each other down and spoil the timings. One worker process runs one experiment at a time; the web process stays responsive; at most 4 requests can be in flight. The process is started with spawn, so it builds its own registry and clock and shares nothing by accident.

الترتيب شغل على الـ CPU. لو اتشغّل في process الويب، هيعطّل باقي الطلبات، ولو اتنين benchmark اشتغلوا مع بعض، هيبطّأوا بعض ويبوّظوا التوقيت. فيه worker process واحدة بتشغّل تجربة واحدة في المرة؛ و process الويب بتفضل سريعة؛ وأقصى عدد طلبات شغالة أو مستنية 4. الـ process بتبدأ بـ spawn، فبتبني الـ registry والـ clock بتوعها لوحدها ومش بتشارك حاجة بالغلط.

Tech stack

التقنيات المستخدمة

Fair measurement

القياس العادل

A benchmark runs three kinds of pass

الـ benchmark فيه تلات أنواع تشغيل

1. Instrument: one pass with counting on and tracing off, to get exact operation counts.
2. Warm up: 0 to 3 untimed passes, so caches and the interpreter settle.
3. Measure: 1 to 15 timed passes with all counting off. Report the median, min, max and spread.

1. Instrument: تشغيلة واحدة والعدّ شغال والتسجيل مقفول، عشان ناخد عدد العمليات بالظبط.
2. Warm up: من 0 لـ 3 تشغيلات من غير توقيت، عشان الـ cache والـ interpreter يستقروا.
3. Measure: من 1 لـ 15 تشغيلة متوقتة والعدّ كله مقفول. وبنطلّع الـ median والأقل والأكبر والفرق بينهم.

Rules that keep it fair

قواعد بتخلّي القياس عادل

• Every algorithm gets a fresh copy of the same input on every pass.
• Only the call to the algorithm is inside the timer: no copying, checking or JSON.
• The order of algorithms is shuffled each round, with a seed, so none always runs first.
• Algorithms run one after the other, never at the same time.
• Median is used for ranking because one slow outlier run does not move it.
• A noise warning appears when the fastest algorithm's range overlaps another's: the ranking might flip on another run. In the app it says "Too close to call".

• كل خوارزمية بتاخد نسخة جديدة من نفس الـ input في كل تشغيلة.
• جوه التوقيت فيه بس نداء الخوارزمية: مفيش نسخ ولا مراجعة ولا JSON.
• ترتيب الخوارزميات بيتلخبط في كل جولة، بـ seed، عشان مفيش واحدة تشتغل الأولى دايمًا.
• الخوارزميات بتشتغل ورا بعض، عمرها ما بتشتغل في نفس الوقت.
• بنرتب بالـ median لأن تشغيلة واحدة بطيئة بالصدفة مش بتأثر عليه.
• بيظهر noise warning لما مدى الوقت بتاع أسرع خوارزمية يتداخل مع مدى واحدة تانية: يعني الترتيب ممكن يتقلب في تشغيلة تانية. في الأبلكيشن بيقول «Too close to call».

Datasets and seeds

الداتا والـ seeds

Five patterns: random, sorted, reversed, nearly sorted (sorted, then n/20 random swaps), few unique (at most five distinct values). The API always returns the seed it used; the same seed and settings rebuild the same data, so every experiment can be repeated.

فيه خمس أنماط: random عشوائي، وsorted مترتب، وreversed معكوس، وnearly sorted شبه مترتب (مترتب وبعدين n/20 تبديل عشوائي)، وfew unique قيم قليلة مختلفة (أقصاها خمس قيم). الـ API دايمًا بيرجّع الـ seed اللي استخدمه؛ ونفس الـ seed مع نفس الإعدادات بيطلّع نفس الداتا، فأي تجربة ممكن تتكرر.

Limits (guardrails)

الحدود (Guardrails)

Numbers to quote

أرقام تقولها

All from the live API on the dev branch. Counts are exact; times are from one machine.

كلها من الـ API شغال على برانش dev. عدد العمليات دقيق؛ والأوقات من جهاز واحد.

Notice Binary Insertion (3.50) beats Insertion (8.26): same writes, far fewer comparisons, and comparisons are expensive in Python.

خد بالك إن Binary Insertion (3.50) أسرع من Insertion (8.26): نفس الكتابات، بس مقارنات أقل بكتير، والمقارنة في Python مكلفة.

Demo script

سيناريو العرض

About five minutes. Do these in order; the bold line is what to say.

حوالي خمس دقايق. اعملهم بالترتيب؛ والسطر اللي بالـ bold هو اللي تقوله.

1. Open the page. "One array, ten possible algorithms, three ways to compare them."
2. In Race, keep Bubble, Insertion and Quick, then add Heap Sort. Press Start race, set 25 steps/s, Play. "Each step is one real operation recorded by the backend."
3. Pause mid-race and point at a pink pair. "Pink is a swap. Insertion Sort never swaps; it shifts with blue writes."
4. Let it finish. "Quick Sort wins with 167 steps; Bubble needs 430." Drag the scrub bar back. "Scrubbing happens in the browser, no new request."
5. Benchmark, Run. "Real timings: median of repeated runs after a warm-up." Hover a bar for the samples, then switch to Comparisons. "Counts are exact; times vary."
6. Suite: tick Sorted and Reversed, Run. Hover the charts. "On sorted data Insertion Sort is the best; on reversed data it is the worst. That is best case versus worst case."
7. Switch to dark mode, then close. "Everything is reproducible with a seed, and new algorithm families plug into the same model."

1. افتح الصفحة. «مصفوفة واحدة، وعشر خوارزميات ممكن نختار منهم، وتلات طرق نقارنهم بيها.»
2. في الـ Race، سيب Bubble و Insertion و Quick وضيف Heap Sort. دوس Start race، وخلّي السرعة 25 خطوة في الثانية، ودوس Play. «كل خطوة عملية حقيقية الباك إند سجّلها.»
3. وقّف في نص السباق وشاور على عمودين بمبي. «البمبي ده swap. Insertion Sort عمره ما بيبدّل؛ بيزق بكتابات زرقا.»
4. سيبه يخلص. «Quick Sort كسب بـ 167 خطوة؛ و Bubble محتاج 430.» اسحب شريط الـ scrub لورا. «الرجوع بيحصل في المتصفح، من غير request جديد.»
5. في الـ Benchmark دوس Run. «أوقات حقيقية: median لتشغيلات متكررة بعد warm-up.» قف بالماوس على عمود عشان تشوف العينات، وبعدين بدّل لـ Comparisons. «عدد العمليات دقيق؛ لكن الوقت بيتغير.»
6. في الـ Suite علّم على Sorted و Reversed ودوس Run. قف بالماوس على الشارتس. «على داتا مترتبة Insertion Sort هي الأحسن؛ وعلى داتا معكوسة هي الأوحش. ده الفرق بين أحسن حالة وأسوأ حالة.»
7. بدّل لـ dark mode، واختم. «كل حاجة تتكرر بنفس الـ seed، وأي عيلة خوارزميات جديدة هتتركب على نفس الفكرة.»

Likely questions

أسئلة متوقعة

Glossary

قاموس المصطلحات

English term, what it means, and how to say it in Arabic.

المصطلح بالإنجليزي، ومعناه، وتقوله إزاي بالعربي.