---

🌟 What is this?

Machine Learning 101 is a free, browser-based platform for building intuition about machine learning. Instead of just reading theory, you experiment: tweak a learning rate and watch gradient descent converge, drag points and see a decision boundary move, add clusters and watch K-means settle.

Everything runs client-side — no installs, no sign-up required, no backend needed. Your progress is saved locally in your browser (with optional cloud sync if you sign in).

Zero setup · Visual-first · Learn by doing · Open source

✨ Features

• 🎯 Interactive learning — Real-time parameter adjustments with immediate visual feedback
• 📊 Rich visualizations — Interactive 2D/3D charts powered by Chart.js, D3.js, and Plotly.js
• 🧪 Hands-on experiments — Train models, tune parameters, and inspect results instantly
• 📚 Guided content — Clear explanations, interactive quizzes, and progress tracking
• 🔒 Privacy-focused — Optional, opt-in analytics with full user control and GDPR compliance
• 📱 Responsive — Works on desktop, tablet, and mobile
• ⚡ Zero setup — No installations, no backend dependencies, no barriers to learning
• 🌐 Fully static — Deployable to any static host (Netlify, Vercel, GitHub Pages)
• 🔐 Optional cloud sync — Sign in to keep progress across devices (Cloudflare Workers + D1)

Learning domains

Domain	Topics
Regression	Linear regression, logistic regression
Classification	KNN, decision trees, SVM
Clustering	K-means, hierarchical clustering
Preprocessing	Feature scaling, encoding, imputation, feature selection
Optimization	Gradient descent, momentum, RMSProp, Adam
Advanced	PCA, t-SNE, neural networks, CNNs, hyperparameter tuning

🚀 Getting Started

Prerequisites

• Node.js 22+ (see .nvmrc — we recommend nvm: nvm use)
• npm 10+

Run Locally

# Clone the repository
git clone https://github.com/marvelefe/machinelearning101.git
cd machinelearning101

# Install dependencies
npm install

# Start the dev server
npm run dev

Open http://localhost:3000 🎉

Useful Commands

Command	Description
npm run dev	Start the development server
npm run build	Build for production
npm run preview	Preview the production build locally
npm run generate	Generate the fully static site
npm run test	Run unit tests (Vitest)
npm run type-check	Run TypeScript type checking

🏗️ Project Structure

.
├── algorithms/          # ML algorithm implementations (extend BaseAlgorithm)
│   ├── advanced/       #   Neural networks, PCA, t-SNE
│   ├── classification/ #   KNN, decision trees, SVM
│   ├── clustering/     #   K-means, hierarchical
│   ├── optimization/   #   Gradient descent variants
│   ├── preprocessing/  #   Scaling, encoding, imputation
│   └── regression/     #   Linear, logistic regression
├── components/          # Vue components
│   ├── layout/         #   Header, footer, navigation
│   ├── modules/        #   Module-specific UI
│   ├── shared/         #   Reusable components
│   └── visualizations/ #   Chart wrappers
├── composables/         # Vue composables (reusable logic)
├── content/            # Learning content (markdown + JSON)
│   └── modules/        #   Organized by domain
├── pages/              # Nuxt pages (auto-routing)
├── stores/             # Pinia state management
├── types/              # TypeScript definitions
├── utils/              # Utility functions
├── tests/              # Unit tests (Vitest)
├── worker/             # Optional Cloudflare Worker (auth backend)
└── service-workers/    # Web Workers (heavy computation)

🛠️ Tech Stack

• Framework: Nuxt 4 (Vue 3 + TypeScript, strict mode)
• State: Pinia with persistence
• Styling: Tailwind CSS
• Visualizations: Chart.js, D3.js, Plotly.js
• Backend (optional): Cloudflare Workers + D1
• Testing: Vitest
• Build: Vite, with static site generation

📚 Documentation

Guide	Description
User Guide	How to use the platform
Developer Guide	Development setup and workflow
Module Creation Guide	Add a new learning module
State Management	How Pinia stores are organized
Quiz Integration	Adding quizzes to modules
Bookmark Integration	Bookmarking support
Core Web Vitals	Performance notes
Deployment Guide	Deploying the site & backend
Worker README	Optional auth backend

🔐 Optional Authentication Backend

Signing in enables cross-device progress sync via Cloudflare Workers + D1 and Google OAuth. This is entirely optional — the site works fully without it. See the Worker README and the Deployment Guide to set it up.

🤝 Contributing

Contributions are warmly welcomed — code, content, docs, design, and bug reports alike! 💚

• 📖 Read the Contributing Guide to get started
• 🙋 Browse good first issues — perfect for newcomers
• 🤝 Check out help wanted issues for meatier tasks
• 💬 Ask questions in Discussions
• 🐛 Report a bug · 💡 Request a feature

Please note that this project is released with a Contributor Code of Conduct. By participating you agree to abide by its terms.

🔒 Security

Found a vulnerability? Please report it privately — see our Security Policy. Do not open a public issue for security concerns.

📄 License

This project is licensed under the MIT License — see the LICENSE file for details.

⭐ Support the Project

If Machine Learning 101 helped you learn something, consider giving it a star ⭐ — it helps others discover the project. And if you'd like to contribute, we'd love to have you!