AlgorithmLab — React + Node.js

The project demonstrates the operation of selected algorithms through interactive visualization.

Its goal is to showcase practical knowledge of algorithms and the ability to implement them in a full-stack application.

Additionally, it integrates Large Language Models (LLMs) through LangChain and OpenAI to generate educational explanations and interview preparation content for users.

🎥 Application Demo

🧮 Sorting Algorithms Visualization

Interactive visualization of Bubble Sort, Selection Sort, Insertion Sort, Merge Sort, Quick Sort, and Heap Sort with step-by-step execution.

🤖 AI Learning Assistant

AI-powered explanations, quiz generation, and RAG-based question answering built with OpenAI, LangChain, embeddings, and semantic search.

☸️ Kubernetes Deployment

Automated Kubernetes deployment with Deployments, Services, Persistent Volume Claims (PVC), Ingress routing, Horizontal Pod Autoscaling (HPA), ConfigMaps, Secrets, and Metrics Server integration. The entire environment can be provisioned using a single startup script.

🛠 Technologies

Frontend: React + Vite
- React — a library for building user interfaces
- Vite — a fast bundler and development server for frontend projects
- React Router — handling navigation and routing between different pages/components
Backend: Node.js + Express
- Node.js — a JavaScript runtime environment for server-side development
- Express — a framework for building APIs and handling HTTP requests
- CORS — middleware that allows communication between frontend and backend running on different ports
- Swagger UI — interactive REST API documentation
- swagger-jsdoc — OpenAPI specification generation from JSDoc comments
Database: PostgreSQL
- PostgreSQL — relational database used to store algorithm descriptions
DevOps: Docker & Docker Compose
- Docker — containerization platform
- Docker Compose — orchestration of frontend, backend and database containers

🤖 AI-Powered Learning Assistant

AlgorithmLab includes an AI-powered educational assistant built with LangChain and OpenAI.

Users can generate detailed explanations for each implemented sorting algorithm directly from the visualization page.

Features

AI-generated algorithm explanations
AI-generated quizzes for self-assessment
RAG-based AI assistant for algorithm questions
OpenAI embeddings for semantic search
PostgreSQL-stored algorithm knowledge base
Source attribution for AI-generated answers
Step-by-step analysis of the provided input array
Time and space complexity discussion
Practical use cases
Interview preparation questions
Knowledge-check questions with answers
Markdown-formatted responses
GitHub Actions CI pipeline
Automated Kubernetes manifest validation
Kubernetes schema verification using kubeconform

Technology Stack

LangChain – orchestration layer for LLM interactions
OpenAI GPT-4o Mini – explanation generation
React Markdown – rendering AI-generated Markdown content
Express.js – backend API integration

Example Workflow

User enters a custom array.
User runs the sorting visualization.
User clicks "🤖 Explain with AI".
Backend sends the algorithm name and input array to OpenAI through LangChain.
AI generates:
- algorithm overview,
- execution walkthrough,
- complexity analysis,
- practical applications,
- interview questions.
Response is displayed in formatted Markdown inside the application.

AI Quiz Generator

AlgorithmLab includes an AI-powered quiz generator that helps users verify their understanding of sorting algorithms.

Users can generate quizzes directly from the visualization page after exploring an algorithm.

Quiz Features

AI-generated knowledge checks
Algorithm-specific questions
Multiple difficulty levels
Answer explanations
Interview-style questions
Markdown-formatted output

Quiz Workflow

User explores a sorting algorithm.
User clicks "🧠 Generate Quiz".
Backend sends the algorithm name and input array to OpenAI through LangChain.
AI generates:
- multiple-choice questions,
- conceptual questions,
- complexity-related questions,
- practical scenario questions,
- answer explanations.
Quiz is displayed directly in the application.

RAG-Based AI Algorithm Assistant

AlgorithmLab includes a Retrieval-Augmented Generation (RAG) assistant that answers natural language questions about sorting algorithms.

The assistant uses algorithm descriptions stored in PostgreSQL as a knowledge base. For each algorithm, the backend generates OpenAI embeddings and stores them in the database. When a user asks a question, the system creates an embedding for the question, compares it with stored algorithm embeddings using cosine similarity, retrieves the most relevant algorithm descriptions, and sends them as context to the LLM through LangChain.

RAG Features

Natural language question answering
OpenAI embeddings
Semantic search over algorithm descriptions
PostgreSQL-based knowledge storage
Cosine similarity retrieval
LangChain-powered answer generation
Source attribution with similarity scores
Markdown-rendered AI responses

RAG Workflow

User asks a question in the AI Assistant page.
Backend generates an embedding for the question.
Stored algorithm embeddings are retrieved from PostgreSQL.
Cosine similarity is used to find the most relevant algorithm descriptions.
Retrieved descriptions are passed as context to the LLM.
The model generates a grounded answer.
The frontend displays the answer together with retrieved sources.

Example question:

Which sorting algorithm is adaptive and has O(n) best-case time complexity?

Supported Algorithms

Bubble Sort
Selection Sort
Insertion Sort
Merge Sort
Quick Sort
Heap Sort

Environment Variables

OPENAI_API_KEY=your_openai_api_key

The application uses the OpenAI API through LangChain to generate educational content dynamically.

📂 Project Structure

AlgorithmLab/
│
├─ frontend/
│  ├─ src/
│  │  ├─ components/
│  │  │  ├─ BubbleSortVisualizer.jsx
│  │  │  ├─ HeapSortVisualizer.jsx
│  │  │  ├─ InsertionSortVisualizer.jsx
│  │  │  ├─ MergeSortVisualizer.jsx
│  │  │  ├─ QuickSortVisualizer.jsx
│  │  │  └─ SelectionSortVisualizer.jsx
│  │  │
│  │  ├─ pages/
│  │  │  ├─ AiAssistant.jsx
│  │  │  └─ Home.jsx
│  │  │
│  │  ├─ App.jsx
│  │  └─ main.jsx
│  │
│  ├─ Dockerfile
│  ├─ package.json
│  └─ vite.config.js
│
├─ backend/
│  ├─ algorithms/
│  │  ├─ bubbleSort.js
│  │  ├─ heapSort.js
│  │  ├─ insertionSort.js
│  │  ├─ mergeSort.js
│  │  ├─ quickSort.js
│  │  └─ selectionSort.js
│  │
│  ├─ db.js
│  ├─ init.sql
│  ├─ server.js
│  ├─ swagger.js
│  ├─ Dockerfile
│  └─ package.json
│
├─ k8s/
│  ├─ namespace.yaml
|  ├─ backend-hpa.yaml
│  ├─ configmap.yaml
│  ├─ secret.example.yaml
│  ├─ postgres-pvc.yaml
│  ├─ postgres-deployment.yaml
│  ├─ postgres-service.yaml
│  ├─ backend-deployment.yaml
│  ├─ backend-service.yaml
│  ├─ frontend-deployment.yaml
|  ├─ ingress.yaml
│  └─ frontend-service.yaml
│
├─ docker-compose.yml
├─ .gitignore
├─ .prettierrc
├─ .prettierignore
├─ eslint.config.js
└─ README.md

Project Architecture

Frontend (React + Vite)
          │
          ▼
Backend (Node.js + Express)
          │
   ┌──────┼────────────┬────────────┐
   ▼      ▼            ▼            ▼
PostgreSQL Cache   OpenAI API   Swagger UI
   │                   ▲
   │                   │
   ├─ algorithm data   │
   ├─ embeddings       │
   └─ AI history       │
                       │
                  LangChain

The frontend communicates with the backend through REST APIs. The backend executes sorting algorithms, retrieves algorithm descriptions from PostgreSQL, and returns data to the frontend. Docker Compose orchestrates all application services.

⚡ AI Performance Optimizations

To improve response times and reduce unnecessary OpenAI API calls, AlgorithmLab includes several backend optimizations.

Shared OpenAI Model Instance

The LangChain ChatOpenAI client is initialized once during server startup and reused across all requests.

Benefits:

lower request overhead
reduced object creation cost
faster response generation

In-Memory AI Cache

Generated explanations are cached using a JavaScript Map.

When a user requests an explanation for the same algorithm and input array, the backend returns the cached response instead of calling OpenAI again.

Example cache key:

QuickSort:5,2,4,3,1

Workflow:

User requests an AI explanation.
Backend generates a cache key from the algorithm name and input array.
If the explanation already exists in cache:
- cached response is returned immediately.
Otherwise:
- OpenAI generates a new explanation,
- the response is stored in cache,
- the generated explanation is returned to the user.

Benefits:

significantly faster repeated requests
reduced OpenAI API usage
lower operational costs
improved user experience

🧠 AI Assistant Features

The AI Assistant combines Retrieval-Augmented Generation (RAG), semantic search, and conversation persistence.

RAG Pipeline

User submits a question.
OpenAI embeddings are generated for the question.
Algorithm descriptions stored in PostgreSQL are compared using cosine similarity.
The most relevant algorithms are selected as context.
LangChain and OpenAI generate a grounded response.
Retrieved sources are returned together with similarity scores.

Conversation History

Every AI Assistant interaction is stored in PostgreSQL.

Stored information:

User question
Generated answer
Retrieved sources
Timestamp

Recent conversations can be retrieved through:

GET /ai/conversations

🌐 Routing in React

The frontend uses React Router to handle navigation between pages.
/ → Home page
/insertion-sort → Insertion Sort Visualizer
/bubble-sort → Bubble Sort Visualizer
/selection-sort → Selection Sort Visualizer
/merge-sort → Merge Sort Visualizer
/quick-sort → Quick Sort Visualizer
/heap-sort → Heap Sort Visualizer
/ai-assistant → RAG-based AI Algorithm Assistant
Each algorithm will eventually have its own route and visualizer component.

This approach allows multiple pages without reloading the browser, which is standard in modern single-page applications (SPA).

🔗 Backend Endpoints

The backend provides REST endpoints for handling sorting and descriptions:

GET /
- Test endpoint, returns AlgorithmLab backend is running
POST /sort/insertion
- Receives JSON { array: [5,2,4,3] }
- Returns the sorting steps and the sorted array
GET /algorithms/:name
- Returns algorithm metadata and description from PostgreSQL
POST /ai/explain
- Receives algorithm name and input array
- Generates AI-powered explanation using LangChain and OpenAI
POST /ai/quiz
- Receives algorithm name and input array
- Generates an AI-powered quiz using LangChain and OpenAI
POST /ai/ask
- Receives a natural language question about sorting algorithms
- Generates a RAG-based answer using OpenAI embeddings, semantic search, PostgreSQL-stored algorithm knowledge, and LangChain
- Returns the answer with retrieved sources and similarity scores

Example:

GET /algorithms/BubbleSort
GET /algorithms/InsertionSort
GET /algorithms/QuickSort

POST /ai/explain

{
  "algorithm": "QuickSort",
  "array": [5, 2, 4, 3, 1]
}

Rest of endpoints works in similar way:

POST /sort/bubble
POST /sort/selection
POST /sort/merge
POST /sort/quick
POST /sort/heap
POST /ai/explain
POST /ai/quiz

API Documentation

Interactive API documentation is available through Swagger UI:

http://localhost:5000/api-docs

🐘 PostgreSQL Integration

Algorithm descriptions are stored in a PostgreSQL database running in Docker.

The backend connects to PostgreSQL using the pg package and exposes a REST endpoint:

GET /algorithms/:name

Example:

GET /algorithms/QuickSort

Response:

{
  "id": 5,
  "name": "QuickSort",
  "description": "Quick Sort is a sorting algorithm..."
}

Database initialization is handled automatically using:

backend/init.sql

which creates the algorithms table and inserts default descriptions for all supported algorithms.

🐳 Docker Setup

The application runs using Docker Compose and consists of three containers:

Frontend (React + Vite)
Backend (Node.js + Express)
PostgreSQL

Architecture:

Frontend (React + Vite)
          │
          ▼
Backend (Node.js + Express)
          │
   ┌──────┼────────────┬────────────┐
   ▼      ▼            ▼            ▼
PostgreSQL Cache   OpenAI API   Swagger UI
   │                   ▲
   │                   │
   ├─ algorithm data   │
   ├─ embeddings       │
   └─ AI history       │
                       │
                  LangChain

Start the entire application:

docker compose up --build

Stop containers:

docker compose down

⚙️ CI / GitHub Actions

This project uses GitHub Actions to automatically run quality checks on push and pull requests.

The workflows check:

Quality Checks

dependency installation
Prettier formatting
ESLint code quality
frontend production build

Workflow file:

.github/workflows/quality-checks.yml

Kubernetes Validation

Kubernetes manifest validation
Schema verification using kubeconform
Validation of Deployments, Services, PVCs, Ingress, ConfigMaps, Secrets, and HPA manifests

Workflow file:

.github/workflows/kubernetess.yml

☸️ Kubernetes Local Deployment

The application can also be tested locally using Kubernetes through Docker Desktop Kubernetes or Minikube.

This setup includes:

Frontend Deployment and Service
Backend Deployment and Service
PostgreSQL Deployment and Service
PersistentVolumeClaim (PVC) for PostgreSQL data persistence
ConfigMap for application configuration
Kubernetes Secret for the OpenAI API key
Namespace isolation for project resources
NGINX Ingress Controller
Ingress resource for frontend routing
Metrics Server for resource monitoring
Horizontal Pod Autoscaler (HPA) for backend autoscaling

1. Enable Kubernetes

If you use Docker Desktop:

Open Docker Desktop
Go to Settings → Kubernetes
Enable Kubernetes
Click Apply & Restart

2. Build local Docker images

From the project root directory run:

docker build -t algorithmlab-backend:latest ./backend
docker build -t algorithmlab-frontend:latest ./frontend

3. Create a local Kubernetes secret

Create a local file:

k8s/secret.yaml

Example:

apiVersion: v1
kind: Secret
metadata:
  name: algorithmlab-secret
  namespace: algorithmlab
type: Opaque
stringData:
  OPENAI_API_KEY: your_real_openai_api_key

This file contains a real API key and should not be committed.

Add it to .gitignore:

k8s/secret.yaml

The repository should only include:

k8s/secret.example.yaml

4. Apply Kubernetes manifests

kubectl apply -f k8s/namespace.yaml
kubectl apply -f k8s/configmap.yaml
kubectl apply -f k8s/secret.yaml
kubectl apply -f k8s/postgres-deployment.yaml
kubectl apply -f k8s/postgres-service.yaml
kubectl apply -f k8s/backend-deployment.yaml
kubectl apply -f k8s/backend-service.yaml
kubectl apply -f k8s/frontend-deployment.yaml
kubectl apply -f k8s/frontend-service.yaml

5. Check Kubernetes resources

kubectl get pods -n algorithmlab
kubectl get services -n algorithmlab

6. PostgreSQL Persistent Storage

AlgorithmLab uses a PersistentVolumeClaim (PVC) to persist PostgreSQL data across pod restarts and redeployments.

Check the PVC status:

kubectl get pvc -n algorithmlab

Expected output:

NAME           STATUS   CAPACITY
postgres-pvc   Bound    1Gi

A Bound status indicates that PostgreSQL storage has been successfully provisioned and attached to the database pod.

This ensures that database data survives:

PostgreSQL pod restarts
Deployment rollouts
Kubernetes pod recreation events

7. Access the application

If NodePort works correctly:

http://localhost:30080

If not, use port forwarding.

Frontend:

kubectl port-forward service/frontend-service 5173:5173 -n algorithmlab

Then open:

http://localhost:5173

Backend:

kubectl port-forward service/backend-service 5000:5000 -n algorithmlab

Then open:

http://localhost:5000/api-docs

This allows the full application to be tested locally on Kubernetes without deploying it to AWS.

8. Access via Ingress

Add the following entry to your hosts file:

127.0.0.1 algorithmlab.local

Then access the application through:

http://algorithmlab.local

9. Horizontal Pod Autoscaling (HPA)

AlgorithmLab includes a Horizontal Pod Autoscaler (HPA) for the backend service.

The HPA automatically scales backend replicas based on CPU utilization.

Configuration:

minReplicas: 1
maxReplicas: 5
averageUtilization: 70

Check HPA status:

kubectl get hpa -n algorithmlab

Example output:

NAME          REFERENCE            TARGETS
backend-hpa   Deployment/backend   cpu: 0%/70%

The backend will automatically scale when CPU utilization exceeds the configured threshold.

Metrics are provided by Kubernetes Metrics Server.

🖼️ Favicon

The application’s avatar (favicon) was generated using Craion, an AI-powered tool that creates images based on short text prompts. Craion uses generative models to produce graphics in various styles, making it easy to generate simple illustrations, icons, or visual concepts. The image used in this project was created specifically for the application and does not depict any real persons or objects.

✨ Features

Interactive visualization of sorting algorithms
AI-powered algorithm explanations using OpenAI and LangChain
AI-powered quiz generation
AI-generated knowledge checks
AI-generated interview questions and answers
In-memory AI caching for explanations and quizzes
RAG-based AI assistant powered by OpenAI embeddings and LangChain
Semantic search over algorithm knowledge stored in PostgreSQL
AI conversation history stored in PostgreSQL
Retrieval of recent AI assistant conversations
Source attribution for AI-generated answers
Algorithm walkthroughs for user-provided arrays
Markdown-rendered educational content
Step-by-step execution
Automatic playback mode
Previous / Next step navigation
Dynamic algorithm descriptions from PostgreSQL
Dockerized frontend, backend, and database
Responsive UI built with Bootstrap
Multiple sorting algorithms:
- Bubble Sort
- Insertion Sort
- Selection Sort
- Merge Sort
- Quick Sort
- Heap Sort
PostgreSQL-backed algorithm descriptions
REST API for algorithm metadata
Interactive API documentation with Swagger UI
Docker Compose local environment
Home navigation shortcut in navbar
Local Kubernetes deployment configuration
Kubernetes Deployments, Services, ConfigMaps, Secrets, and PersistentVolumeClaims
Persistent PostgreSQL storage using PersistentVolumeClaim (PVC)
Namespace-based resource isolation
Kubernetes Ingress for application routing
Metrics Server integration
Horizontal Pod Autoscaler (HPA) for backend autoscaling

🏃‍♂️ Running the project

Start the entire application:

docker compose up --build

Frontend:

http://localhost:5173

Backend:

http://localhost:5000

Swagger UI:

http://localhost:5000/api-docs

PostgreSQL:

localhost:5432

🎨 Code Formatting

This project uses Prettier to maintain consistent code style across the frontend and backend.

Format all files

From the project root directory run:

npm run format

Check formatting without modifying files

npm run format:check

Configuration

Prettier configuration is stored in:

.prettierrc
.prettierignore

Formatting is applied to the entire project, including:

Frontend (React + Vite)
Backend (Node.js + Express)
Configuration files
Documentation files

🔍 Code Linting

This project uses ESLint to detect potential issues and enforce code quality standards.

Run lint checks

From the project root directory run:

npm run lint

Automatically fix lint issues

npm run lint:fix

What ESLint checks

React Hooks rules
JavaScript best practices
Unused variables
Potential code quality issues
Consistent coding patterns

✅ Code Quality

ESLint static code analysis
Prettier code formatting
Consistent coding style
Modular project structure
React Hooks linting
Automated formatting scripts

FilesExpand file tree

README.md

Latest commit

History

README.md

File metadata and controls

AlgorithmLab — React + Node.js

🎥 Application Demo

🧮 Sorting Algorithms Visualization

🤖 AI Learning Assistant

☸️ Kubernetes Deployment

🛠 Technologies

🤖 AI-Powered Learning Assistant

Features

Technology Stack

Example Workflow

AI Quiz Generator

Quiz Features

Quiz Workflow

RAG-Based AI Algorithm Assistant

RAG Features

RAG Workflow

Supported Algorithms

Environment Variables

📂 Project Structure

Project Architecture

⚡ AI Performance Optimizations

Shared OpenAI Model Instance

In-Memory AI Cache

🧠 AI Assistant Features

RAG Pipeline

Conversation History

🌐 Routing in React

🔗 Backend Endpoints

API Documentation

🐘 PostgreSQL Integration

🐳 Docker Setup

⚙️ CI / GitHub Actions

Quality Checks

Kubernetes Validation

☸️ Kubernetes Local Deployment

1. Enable Kubernetes

2. Build local Docker images

3. Create a local Kubernetes secret

4. Apply Kubernetes manifests

5. Check Kubernetes resources

6. PostgreSQL Persistent Storage

7. Access the application

8. Access via Ingress

9. Horizontal Pod Autoscaling (HPA)

🖼️ Favicon

✨ Features

🏃‍♂️ Running the project

🎨 Code Formatting

Format all files

Check formatting without modifying files

Configuration

🔍 Code Linting

Run lint checks

Automatically fix lint issues

What ESLint checks

✅ Code Quality