🎯 KMeans Visualizer

Interactive machine learning visualization application that demonstrates how the K-Means Clustering algorithm works step by step.

The project is designed as an educational tool for learning machine learning fundamentals, clustering algorithms, data visualization, and modern software engineering practices.

---

🎬 Application Demo

☸️ Kubernetes Deployment Demo

---

✨ Current Features

📊 Dataset Generator

• Generate random 2D datasets
• Configure the number of points
• Return datasets through FastAPI API
• Prepare datasets for clustering experiments

🎯 K-Means Clustering Engine

• Custom K-Means implementation using NumPy
• Configurable number of clusters (k)
• Configurable maximum number of iterations
• Random centroid initialization
• Point-to-centroid assignment
• Centroid recalculation
• Inertia (loss) calculation
• Iteration history tracking
• Final centroid calculation

🐳 Dockerized Development Environment

• Backend Docker container
• Frontend Docker container
• Docker Compose orchestration
• One-command local environment startup
• Containerized FastAPI application
• Containerized React application

☸️ Kubernetes Deployment

• Backend Deployment
• Frontend Deployment
• Backend Service
• Frontend Service
• Kubernetes Ingress
• Internal service discovery
• Container orchestration with Kubernetes
• Local Kubernetes deployment support

📈 Kubernetes Scaling & Monitoring

• Backend Horizontal Pod Autoscaler (HPA)
• CPU-based autoscaling configuration
• Kubernetes ConfigMap configuration management
• Resource requests and limits
• Liveness probes
• Readiness probes
• Health monitoring through Kubernetes

⚡ Kubernetes Automation

• One-command Kubernetes deployment
• Automatic Docker image builds
• Automatic Kubernetes resource deployment
• Automated deployment rollout verification
• Automated cluster cleanup
• Automated port-forwarding setup

🚧 Planned Features

• Enhanced centroid movement visualization
• Inertia charts
• Cluster assignment visualization improvements
• Responsive UI
• Dark mode
• Linear Regression Visualizer

🔄 Continuous Integration

• Automated backend quality checks
• Automated frontend linting
• Automated frontend production build verification
• Automated Docker image builds
• Automated Kubernetes manifest validation
• GitHub Actions CI workflow

---

🛠️ Tech Stack

Backend

• Python 3.13
• FastAPI
• NumPy

Frontend

• React
• Vite
• JavaScript
• Axios
• SVG Visualization

DevOps

• Docker
• Docker Compose
• Kubernetes
• Ingress
• GitHub Actions

---

📁 Project Structure

KMeansVisualizer/
.github/
├── workflows/
│    └── ci.yml
├── backend/
│   ├── schemas/
│   │   ├── __init__.py
│   │   ├── dataset.py
│   │   └── kmeans.py
│   │
│   ├── services/
│   │   ├── __init__.py
│   │   ├── dataset_service.py
│   │   └── kmeans_service.py
│   │
│   ├── Dockerfile
│   ├── .dockerignore
│   ├── main.py
│   ├── requirements.txt
│   └── pyproject.toml
│
├── frontend/
│   ├── public/
│   │
│   ├── src/
│   │   ├── assets/
│   │   ├── components/
│   │   │   ├── ClusteringMetrics.jsx
│   │   │   ├── DatasetGenerator.jsx
│   │   │   ├── IterationControls.jsx
│   │   │   ├── KMeansControls.jsx
│   │   │   └── ScatterPlot.jsx
│   │   │
│   │   ├── services/
│   │   │   └── api.js
│   │   │
│   │   ├── App.jsx
│   │   ├── App.css
│   │   ├── index.css
│   │   └── main.jsx
│   │
│   ├── Dockerfile
│   ├── .dockerignore
│   ├── package.json
│   ├── package-lock.json
│   ├── vite.config.js
│   └── eslint.config.js
│
├── k8s/
│   ├── backend-deployment.yaml
│   ├── backend-service.yaml
│   ├── frontend-deployment.yaml
│   ├── frontend-service.yaml
│   ├── backend-hpa.yaml
│   ├── configmap.yaml
│   └── ingress.yaml
│
├── scripts/
│   ├── deploy-k8s.ps1
│   ├── destroy-k8s.ps1
│   └── port-forward.ps1
│
├── docker-compose.yml
├── README.md
└── .gitignore

---

🚀 Backend Setup

Clone Repository

git clone <repository-url>
cd KMeansVisualizer

Create Virtual Environment

cd backend
py -m venv venv

Activate Virtual Environment

.\venv\Scripts\Activate.ps1

Install Dependencies

pip install -r requirements.txt

Run Backend

python -m uvicorn main:app --reload

Backend will be available at:

http://localhost:8000

Swagger UI:

http://localhost:8000/docs

---

💻 Frontend Setup

Install Dependencies

cd frontend
npm install

Run Frontend

npm run dev

Frontend will be available at:

http://localhost:5173

Verify Frontend Build

npm run build

---

🐳 Docker Setup

Build and Start All Services

docker compose up --build

Services will be available at:

Frontend: http://localhost:5173
Backend:  http://localhost:8000
Swagger:  http://localhost:8000/docs

Stop Services

docker compose down

---

☸️ Kubernetes Setup

Build Local Docker Images

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

Deploy to Kubernetes

kubectl apply -f k8s/

Verify Resources

kubectl get pods
kubectl get services
kubectl get ingress

Verify Horizontal Pod Autoscaler

kubectl get hpa
kubectl describe hpa kmeans-backend-hpa

Verify ConfigMap

kubectl get configmaps
kubectl describe configmap kmeans-config

Inspect Pod Health

kubectl describe pod <pod-name>

Access Backend

kubectl port-forward service/kmeans-backend-service 8000:8000

Backend will be available at:

http://localhost:8000

Access Frontend

kubectl port-forward service/kmeans-frontend-service 5173:5173

Frontend will be available at:

http://localhost:5173

Remove Kubernetes Resources

kubectl delete -f k8s/

---

⚡ Kubernetes Automation Scripts

Deploy Entire Environment

.\scripts\deploy-k8s.ps1

This script:

• Removes previous Kubernetes resources
• Builds backend Docker image
• Builds frontend Docker image
• Deploys all Kubernetes manifests
• Waits for deployment rollout
• Displays cluster status

Remove Entire Environment

.\scripts\destroy-k8s.ps1

This script:

• Removes all Kubernetes resources
• Displays remaining cluster resources

Start Port Forwarding

.\scripts\port-forward.ps1

This script:

• Opens backend port forwarding
• Opens frontend port forwarding
• Provides local access to the application

---

🔗 Available Endpoints

Health Check

GET /health

Response:

{
  "status": "ok"
}

Generate Dataset

POST /datasets/generate

Request:

{
  "points": 100
}

Response:

{
  "points": [
    [12.5, 45.1],
    [22.8, 11.3]
  ]
}

Run K-Means

POST /kmeans/steps

Request:

{
  "points": [
    [1, 2],
    [2, 1],
    [8, 9],
    [9, 8]
  ],
  "k": 2,
  "max_iterations": 10
}

Response:

{
  "iterations": [...],
  "final_centroids": [...]
}

---

📚 API Documentation

Swagger UI:

http://localhost:8000/docs

---

📸 Current Application Preview

Frontend

• Dataset generation UI
• K-Means execution UI
• Scatter plot visualization
• Cluster color visualization
• Centroid visualization
• Iteration slider
• Previous / Next controls
• Play / Pause animation
• Reset animation
• Clustering metrics dashboard

Backend

• Root API endpoint
• Health check endpoint
• Dataset generation API
• K-Means clustering API
• Iteration tracking
• Inertia calculation
• Swagger documentation

Infrastructure

• Dockerized backend
• Dockerized frontend
• Docker Compose environment
• Kubernetes deployments
• Kubernetes services
• Kubernetes ingress
• Horizontal Pod Autoscaler (HPA)
• ConfigMap-based configuration
• Health monitoring probes
• Resource limits and requests
• Automated Kubernetes deployment scripts
• Automated Kubernetes cleanup scripts
• Automated port-forwarding scripts

---

🔄 GitHub Actions CI

The project includes an automated CI workflow executed on every push and pull request.

Automated Checks

• Backend Ruff linting
• Backend Black formatting verification
• Frontend ESLint verification
• Frontend production build verification
• Backend Docker image build
• Frontend Docker image build
• Kubernetes manifest validation

Workflow File

.github/workflows/ci.yml

---

✅ Code Quality

Backend Code Formatting

cd backend
py -m black .

Run Backend Linter

cd backend
py -m ruff check .

Auto-Fix Backend Linter Issues

cd backend
py -m ruff check . --fix

Frontend Lint

cd frontend
npm run lint

Validate Docker Compose

docker compose config

Build Backend Docker Image

docker build -t kmeans-backend ./backend

Build Frontend Docker Image

docker build -t kmeans-frontend ./frontend

Validate Kubernetes Resources

kubectl apply --dry-run=client -f k8s/

View Kubernetes Resources

kubectl get pods
kubectl get services
kubectl get ingress

View Horizontal Pod Autoscaler

kubectl get hpa

Describe HPA

kubectl describe hpa kmeans-backend-hpa

View ConfigMaps

kubectl get configmaps

Inspect Pod Health

kubectl describe pod <pod-name>

---

🔧 Development Tools

• Black - Python formatter
• Ruff - Python linter
• React - Frontend UI
• Vite - Frontend tooling
• Axios - API communication
• FastAPI - Backend API
• Swagger UI - API documentation
• Docker - Containerization
• Docker Compose - Local orchestration
• Kubernetes - Container orchestration
• Ingress - Traffic routing
• Horizontal Pod Autoscaler (HPA) - Automatic scaling
• ConfigMap - Configuration management
• Liveness Probe - Container health checks
• Readiness Probe - Traffic readiness checks
• PowerShell Scripts - Kubernetes automation
• GitHub Actions - Continuous Integration

---

🎓 Learning Goals

This project demonstrates:

• Machine Learning Fundamentals
• K-Means Clustering Algorithm
• Numerical Computing with NumPy
• FastAPI Backend Development
• API Design and Validation
• React State Management
• API Integration with Axios
• Interactive Algorithm Visualization
• Frontend-Backend Communication
• Data Visualization
• Docker Containerization
• Docker Compose Orchestration
• Kubernetes Deployments
• Kubernetes Services
• Kubernetes Ingress
• Kubernetes Horizontal Pod Autoscaling
• Kubernetes ConfigMaps
• Kubernetes Health Checks
• Resource Management in Kubernetes
• Application Monitoring Concepts
• Infrastructure Automation
• Kubernetes Operational Workflows
• Deployment Automation
• CI/CD Automation