CodeMath Homepage

CodeMath: An Interactive Math Learning Platform ๐Ÿงฎ

Iโ€™m excited to introduce my latest open-source project โ€” CodeMath, an interactive math learning platform built with modern web technologies.

The Inspiration

Mathematics is the foundation of computer science, but traditional learning methods often make it feel abstract and intimidating. I wanted to create something different โ€” a platform where mathematical concepts come alive through interaction and visualization.

CodeMath is inspired by the book โ€œMathematics for Programmersโ€ (็จ‹ๅบๅ‘˜็š„ๆ•ฐๅญฆ) by Hiroshi Yuki. The chapter topics and learning path follow the bookโ€™s structure, while all code implementations, interactive components, and visualizations are original work.

Core Features

๐ŸŽฎ Interactive Chapters

Each chapter features hands-on interactive content that helps you understand concepts by doing:

  • Chapter 1: The Story of Zero โ€” Base converter, bitwise visualization
  • Chapter 2: Logic โ€” Logic gate playground, truth table generator
  • Chapter 3: Remainders โ€” Day calculator, chess magic trick
  • Chapter 4: Mathematical Induction โ€” Domino simulator
  • Chapter 5: Permutations & Combinations โ€” Card lab, Venn diagrams
  • Chapter 6: Recursion โ€” Tower of Hanoi, fractals
  • Chapter 7: Exponential Explosion โ€” Paper folding, binary vs linear search
  • Chapter 8: Unsolvable Problems โ€” Halting problem simulator
  • Appendix: Machine Learning โ€” Perceptron training ground

๐ŸŒ Smart Localization

  • Bilingual support (Chinese/English)
  • Auto-detects your preferred language
  • Easy language switching

๐Ÿš€ Developer Experience

  • One-command startup โ€” ./start.sh handles everything
  • Auto-install dependencies on first run
  • Background server mode with PID management
  • Comprehensive logging to logs/startup.log
  • Smart registry โ€” Auto-switches to Taobao npm registry in China

Tech Stack

Frontend

  • React 19 โ€” Latest features and performance
  • TypeScript โ€” Type-safe development
  • Vite โ€” Lightning-fast build tool
  • Tailwind CSS โ€” Utility-first styling
  • shadcn/ui โ€” Beautiful, accessible components

Animation & Visualization

  • GSAP โ€” Professional-grade animations
  • Three.js โ€” 3D rendering and effects
  • KaTeX โ€” Fast, beautiful math typesetting
  • Lenis โ€” Smooth scroll experience

Quick Start

Clone and Run

git clone https://github.com/hugcosmos/CodeMath.git
cd CodeMath
./start.sh

The script will:

  1. Ask if youโ€™re in mainland China (auto-configure npm registry)
  2. Auto-install dependencies on first run
  3. Start the dev server in background
  4. Log all output to logs/startup.log

Visit: http://localhost:5173/

Manual Setup

cd app
npm install
npm run dev    # Start dev server
npm run build  # Build for production
npm run preview  # Preview production build

Live Demo

Try it online: https://codemath.pages.dev/

Project Structure

CodeMath/
โ”œโ”€โ”€ app/                    # Main application
โ”‚   โ”œโ”€โ”€ src/
โ”‚   โ”‚   โ”œโ”€โ”€ components/     # Reusable components
โ”‚   โ”‚   โ”œโ”€โ”€ sections/       # Page sections
โ”‚   โ”‚   โ”œโ”€โ”€ chapters/       # Chapter interactives
โ”‚   โ”‚   โ”œโ”€โ”€ hooks/          # Custom hooks
โ”‚   โ”‚   โ”œโ”€โ”€ lib/            # Utilities
โ”‚   โ”‚   โ””โ”€โ”€ i18n/           # i18n configuration
โ”‚   โ”œโ”€โ”€ package.json
โ”‚   โ””โ”€โ”€ vite.config.ts
โ”œโ”€โ”€ logs/                   # Logs directory
โ”œโ”€โ”€ start.sh                # Start script โญ
โ”œโ”€โ”€ stop.sh                 # Stop script โญ
โ”œโ”€โ”€ README.md               # Project README
โ””โ”€โ”€ tech-spec.md            # Tech specification

FAQ

Q: What if port 5173 is occupied? A: Run ./stop.sh to stop existing process, or manually change port in app/vite.config.ts.

Q: How to switch npm registry? A: Script auto-detects environment. Manual switch:

npm config set registry https://registry.npmmirror.com  # Taobao
npm config set registry https://registry.npmjs.org       # Official

Q: Dependency installation failed? A: Delete app/node_modules and app/package-lock.json, then re-run ./start.sh.

Philosophy

๐Ÿ’ก Math shouldnโ€™t be just formulas and theorems โ€” it should be tangible and explorable.

CodeMath embodies this philosophy by making abstract concepts visual, interactive, and fun.

License

MIT License โ€” Completely open-source. Contributions welcome!

Made with ๐Ÿ’™ by Nicky & AI