📋 Table of Contents

• 🌟 Overview
• ✨ Key Features
• 🚀 Getting Started
• 🏗️ Project Structure
• 🛠️ Technology Stack
• 📝 License

🌟 Overview

Algorithm Samurai is the frontend for a learning platform that helps you improve your coding skills through interactive exercises and challenges. This project was built as my first full-stack application to practice React and TypeScript development. It works together with the Algorithm Sensei Backend to provide a complete learning experience with AI-powered hints, real-time code execution, and structured courses.

✨ Key Features

• Live Code Editor: Monaco Editor with syntax highlighting, auto-completion, and real-time feedback
• Instant Code Execution: Run JavaScript code with immediate results using Piston API
• Type-Safe API: Full TypeScript integration with auto-generated types from backend OpenAPI schemas
• Structured Learning: Progressive courses with chapter-based organization and hands-on exercises
• Progress Tracking: Visual indicators to monitor your learning journey
• Dual Theme Support: Light and dark modes with Catppuccin color palette for a pleasant coding experience

🤖 AI Integration

• Intelligent Hints: Context-aware suggestions based on your current code
• Error Analysis: Detailed explanations of runtime errors and compilation issues
• Personalized Learning: Adaptive difficulty based on your progress

🚀 Getting Started

Prerequisites

• Node.js
• npm or yarn package manager
• Backend API: This frontend requires the Algorithm Sensei Backend to be running

Installation

1. Set up the backend first

   git clone https://github.com/philippspitzley/algorithm-sensei.git
   cd algorithm-sensei
   # Follow the backend setup instructions in its README

2. Clone the frontend repository

   git clone https://github.com/philippspitzley/algorithm-samurai.git
   cd algorithm-samurai

3. Install dependencies

4. Set up environment variables

   Fill in your backend url:

   • Backend API URL (default: http://localhost:8000)

5. Start the development server

6. Open your browser Navigate to http://localhost:5173

Note: Make sure the Algorithm Sensei Backend is running.

💡 Tip: After backend changes (new routes, schemas, or data models), run npm run generate:openapi to update TypeScript types for full type safety. See more on OpenAPI Integration

Development Scripts

🏗️ Project Structure

src/
├── components/          # Reusable UI components
│   ├── Admin/          # Admin-specific components
│   ├── Chapter/        # Chapter navigation and content
│   ├── CodeElements/   # Code editor and execution
│   ├── Courses/        # Course management
│   ├── Markdown/       # Markdown rendering
│   └── ui/             # Base UI components (shadcn/ui)
├── context/            # React context providers
│   ├── auth/          # Authentication context
│   ├── theme/         # Theme management
│   └── userCourses/   # User progress tracking
├── hooks/             # Custom React hooks
├── lib/               # Utility functions
├── pages/             # Page components
└── api/               # API client and types

🛠️ Technology Stack

Frontend

• React 19 - Modern UI library with latest features
• TypeScript - Type-safe JavaScript for better development experience
• Vite - Fast build tool and development server
• TailwindCSS - Utility-first CSS framework
• Shadcn - Component library with pre-styled Radix UI primitives

Code Execution & AI

• Monaco Editor - VS Code-powered code editor
• Piston API - Secure code execution environment
• Shiki - Syntax highlighting for code blocks
• Gemini AI Tutor - Integration of AI-powered learning assistant from Algorithm Sensei Backend

State Management & Data

• TanStack Query - Powerful data fetching and caching
• React Hook Form - Efficient form handling
• Zod - Runtime type validation

Development Tools

• ESLint - Code linting and quality checks
• Prettier - Code formatting
• Husky - Git hooks for quality assurance
• OpenAPI TS - Type-safe API client generation of openapi types from Algorithm Sensei Backend

OpenAPI Integration

This project uses type-safe API communication with the Algorithm Sensei backend through automatically generated TypeScript types.

How it works:

• The backend exposes an OpenAPI specification at /api/v1/openapi.json
• TypeScript types are automatically generated from backend schemas
• All API calls are fully type-safe with autocompletion and error checking

Generating API Types:

# Generate TypeScript types from backend OpenAPI schemas
npm run generate:openapi

When to regenerate types:

• After backend API changes - When new endpoints or data models are added

💡 Tip: The generated types are located in ./src/api/openapi-schemas.d.ts and should not be edited manually. If you run the backend without any changes there is no need to generate new types.

📝 License

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

Built with ❤️