ALGO — Interactive Algorithm & Data Structure Visualization Platform

بازطراحی و توسعه‌ی ابزار تعاملی آموزش و مصورسازی الگوریتم‌ها و ساختمان داده‌ها

Redesign and Development of an Interactive Educational Visualization Tool for Algorithms and Data Structures

دانشگاه اصفهان — دانشکده‌ی مهندسی کامپیوتر — گروه مهندسی نرم‌افزار

پروژه‌ی کارشناسی | پژوهشگر: زهرا ابراهیمی

آدرس سامانه : algovisualizer.pages.dev

---

🎯 هدف پروژه (Project Goals)

این پروژه با هدف بازطراحی و توسعه‌ی یک سامانه‌ی تعاملی برای آموزش، تمرین، ارزیابی و مصورسازی الگوریتم‌ها انجام شده است. معماری اصلی سامانه شامل سه لایه‌ی مستقل Recorder، Framer و Renderer حفظ شده و قابلیت‌های آموزشی و تعاملی جدیدی در برنامه‌ی وب توسعه یافته‌اند.

مهم‌ترین قابلیت‌های توسعه‌یافته عبارت‌اند از:

• ورود دستی داده، تولید داده‌ی تصادفی و تولید داده بر اساس الگوهای مشخص
• کنترل اجرای الگوریتم و حرکت میان مراحل مختلف اجرا
• هم‌گامی اجرای بصری با شبه‌کد؛ شامل مشخص‌شدن خط جاری و نمایش توضیح مرحله
• بخش‌های Learn، Practice و Test برای هر الگوریتم
• مقایسه‌ی مستقیم دو الگوریتم روی یک داده‌ی ورودی مشترک
• سیستم آزمون در سه سطح ساده، متوسط و دشوار
• پشتیبانی از زبان‌های فارسی و انگلیسی و چیدمان RTL/LTR
• پشتیبانی از پوسته‌ی روشن و تاریک
• دریافت خروجی LaTeX متناظر با اجرای جاری الگوریتم
• مدیریت پویا‌ی محتوای آموزشی و داده‌های آزمون با استفاده از پایگاه‌داده
• امکان مصورسازی الگوریتم‌های سفارشی برای دسته‌های الگوریتمی پشتیبانی‌شده

الگوریتم‌های از پیش تعریف‌شده‌ی سامانه شامل Bubble Sort، Selection Sort، Insertion Sort، Merge Sort، Quick Sort، Linear Search، Binary Search، DFS، BFS، Dijkstra و A* هستند.

در کنار این الگوریتم‌ها، بخش Custom Algorithms امکان اجرای کد پایتون کاربر و مصورسازی تغییرات حاصل از اجرای آن را فراهم می‌کند. در نسخه‌ی حاضر، این قابلیت برای برخی دسته‌های الگوریتمی از جمله مرتب‌سازی، پشته و صف پشتیبانی می‌شود.

---

🏗️ معماری کلی

پروژه به‌صورت یک Monorepo سازمان‌دهی شده و هسته‌ی مصورسازی آن از سه ماژول مستقل تشکیل می‌شود که خروجی آن‌ها توسط برنامه‌های نمونه مصرف می‌شود:

Final Project/                      ← ریشه‌ی workspace
├─ modules/
│  ├─ recorder/                     ← typescript-recorder
│  │                                  ثبت رخدادهای الگوریتم
│  │
│  ├─ framer/                       ← typescript-framer
│  │                                  تبدیل رخدادها به قاب‌های اجرا
│  │
│  └─ renderer/                     ← typescript-angular-renderer
│                                     خروجی وب و LaTeX
│
└─ examples/
   ├─ web-examples/                 ← ★ برنامه‌ی اصلی و فعال پروژه
   │                                  برنامه‌ی وب Angular
   │
   └─ latex-examples/               ← نمونه‌های مستقل خروجی LaTeX/PDF

سه لایه‌ی اصلی هسته‌ی مصورسازی عبارت‌اند از:

لایه	مسئولیت
Recorder	ثبت رخدادهای اجرای الگوریتم، مانند مقایسه و جابه‌جایی
Framer	تبدیل رخدادهای ثبت‌شده به دنباله‌ای از قاب‌های کامل وضعیت
Renderer	تبدیل قاب‌ها به خروجی نهایی، شامل نمایش وب یا خروجی LaTeX

این معماری امکان جداسازی منطق ثبت و پردازش مراحل اجرا از نحوه‌ی نمایش آن‌ها را فراهم می‌کند.

---

🗄️ پایگاه‌داده و Backend

سامانه از Supabase برای بخش‌های مرتبط با داده و حساب کاربری استفاده می‌کند.

موارد زیر در پایگاه‌داده نگهداری می‌شوند:

• اطلاعات حساب‌های کاربری و احراز هویت
• محتوای آموزشی الگوریتم‌ها
• داده‌های مورد استفاده در آزمون‌ها
• نتایج آزمون کاربران

محتوای آموزشی الگوریتم‌ها شامل اطلاعاتی مانند معرفی، نحوه‌ی عملکرد، پیچیدگی زمانی و فضایی، مزایا و معایب، کاربردها و اطلاعات پیاده‌سازی است و برای زبان‌های فارسی و انگلیسی نگهداری می‌شود.

کاربران مهمان نیز می‌توانند از بخش‌های عمومی سامانه مانند یادگیری، تمرین، مقایسه و آزمون استفاده کنند. اطلاعات وابسته به حساب کاربری، مانند سابقه‌ی نتایج آزمون، برای کاربران واردشده ذخیره می‌شود.

پیشرفت سطح آزمون کاربران مهمان در حافظه‌ی محلی مرورگر نگهداری می‌شود.

---

🚀 نصب و راه‌اندازی سریع (Quick Start)

برنامه‌ی اصلی پروژه در پوشه‌ی examples/web-examples قرار دارد.

پیش‌نیازها

• Node.js
• npm

۱. کامپایل ماژول‌های هسته

ابتدا هر سه ماژول هسته را build کنید. ترتیب اجرای آن‌ها به دلیل وابستگی میان ماژول‌ها به‌صورت زیر است:

cd modules/recorder
npm install
npm run build

cd ../framer
npm install
npm run build

cd ../renderer
npm install
npm run build

در صورت ایجاد تغییر در یکی از ماژول‌های هسته، برای مشاهده‌ی تغییرات در برنامه‌ی وب، باید همان ماژول دوباره build شود.

۲. اجرای برنامه‌ی وب

به پوشه‌ی برنامه‌ی اصلی بروید:

cd examples/web-examples
npm install
ng serve

سپس برنامه را در مرورگر باز کنید:

http://localhost:4200

این بخش، برنامه‌ی اصلی و رابط کاربری نهایی پروژه است و قابلیت‌های Learn، Practice، Test، Compare و Custom Algorithms در آن قرار دارند.

---

🧩 مصورسازی الگوریتم‌های سفارشی (Custom Algorithms)

سامانه علاوه بر الگوریتم‌های از پیش تعریف‌شده، امکان اجرای کد پایتون کاربر و مصورسازی تغییرات حاصل از اجرای آن را نیز فراهم می‌کند.

در این بخش، رخدادهای حاصل از اجرای کد برای ایجاد مراحل مصورسازی مورد استفاده قرار می‌گیرند. در نتیجه، تغییرات واقعی ساختار داده در طول اجرا قابل مشاهده هستند؛ برای نمونه، در الگوریتم‌های مرتب‌سازی جابه‌جایی عناصر و در عملیات مربوط به پشته و صف، اضافه‌شدن یا حذف‌شدن داده‌ها در مصورسازی نمایش داده می‌شود.

این قابلیت در نسخه‌ی حاضر برای برخی دسته‌های الگوریتمی پشتیبانی می‌شود و ساختار آن قابلیت توسعه برای دسته‌های بیشتر را دارد.

---

📄 خروجی LaTeX

خروجی LaTeX در برنامه‌ی اصلی وب از طریق صفحه‌ی Practice در دسترس است. سامانه بر اساس الگوریتم، داده‌ی ورودی و وضعیت اجرای جاری، کد LaTeX متناظر با همان اجرا را تولید می‌کند.

این خروجی می‌تواند برای مستندسازی اجرای الگوریتم یا تهیه‌ی محتوای آموزشی مورد استفاده قرار گیرد.

برنامه‌ی وب در نسخه‌ی حاضر کد LaTeX را تولید می‌کند و تبدیل خودکار آن به PDF را انجام نمی‌دهد.

برای تولید مستقیم فایل PDF، پوشه‌ی examples/latex-examples شامل نمونه‌های مستقل اجرای الگوریتم است که می‌توانند فایل‌های .tex و .pdf تولید کنند.

---

📁 نمونه‌های LaTeX و PDF

پوشه‌ی examples/latex-examples شامل چند فایل TypeScript نمونه است که با استفاده از:

• TypeScript Recorder
• TypeScript Framer
• TypeScript LaTeX Renderer

یک الگوریتم را اجرا کرده و خروجی LaTeX تولید می‌کنند.

در این بخش، پس از اجرای نمونه و در صورت نصب بودن LaTeX، فایل .tex با استفاده از pdflatex به فایل .pdf تبدیل می‌شود.

پیش‌نیازها

• Node.js و npm
• نصب بودن LaTeX
• در دسترس بودن دستور pdflatex به‌صورت سراسری

نصب

cd examples/latex-examples
npm install

اجرای نمونه

ابتدا وارد پوشه‌ی src شوید:

cd src

سپس فایل موردنظر را با ts-node اجرا کنید:

npx ts-node name-of-file.ts

برای مثال:

npx ts-node a-star.ts

خروجی

فایل‌های خروجی در پوشه‌ی src/output قرار می‌گیرند. برای هر نمونه، یک پوشه‌ی جداگانه ایجاد می‌شود:

src/output/a-star/

├─ a-star.tex
└─ a-star.pdf

بنابراین این پوشه با برنامه‌ی web-examples تفاوت دارد: web-examples برنامه‌ی اصلی و تعاملی پروژه است، در حالی که latex-examples نمونه‌های مستقل برای اجرای مستقیم و تولید خروجی LaTeX/PDF را در اختیار قرار می‌دهد.

---

📁 مستندات مرتبط

دو README اختصاصی برای بخش‌های اصلی پروژه وجود دارد:

• examples/web-examples/README.md — راه‌اندازی و جزئیات برنامه‌ی اصلی Angular
• examples/latex-examples/README.md — اجرای نمونه‌های مستقل LaTeX و PDF

این README نمای کلی پروژه، معماری و روش راه‌اندازی را ارائه می‌کند و جزئیات اختصاصی هر بخش در README مربوط به همان بخش قرار دارد.

---

🧰 پشته‌ی فناوری (Tech Stack)

بخش	فناوری
فرانت‌اند	Angular 20، TypeScript، SCSS
هسته‌ی مصورسازی	TypeScript — Recorder / Framer / Renderer
ساختار پروژه	Monorepo
Backend	Supabase
پایگاه‌داده	PostgreSQL از طریق Supabase
احراز هویت	Supabase Auth
خروجی مستند	LaTeX
تبدیل PDF در نمونه‌های مستقل	pdflatex
آیکون‌ها	Solar Icons (@solar-icons/angular)
طراحی	Figma
فونت	Vazirmatn

---

🩹 مشکلات رایج (Troubleshooting)

تغییرات ماژول‌های هسته در برنامه‌ی وب دیده نمی‌شود

اگر پس از تغییر یکی از ماژول‌های recorder، framer یا renderer تغییرات در برنامه‌ی وب دیده نشد، ابتدا همان ماژول را دوباره build کنید.

در صورت ادامه‌ی مشکل، کش Angular را پاک کرده و برنامه را دوباره اجرا کنید:

examples/web-examples/.angular/cache

آیکون‌های Solar نصب نمی‌شوند

پکیج @solar-icons/angular باید در پوشه‌ی examples/web-examples نصب شده باشد.

تولید PDF در latex-examples انجام نمی‌شود

مطمئن شوید LaTeX روی سیستم نصب شده و دستور زیر در محیط خط فرمان قابل اجراست:

pdflatex --version

همچنین اجرای نمونه‌ها باید از مسیر زیر انجام شود:

examples/latex-examples/src

---

📄 مستندات پروژه

• ALGO — سامانه‌ی آموزش و مصورسازی الگوریتم‌ها
• دانشگاه اصفهان
• پروژه‌ی کارشناسی مهندسی کامپیوتر
• ۱۴۰۵