From 69b5ff566ba3b458ad0341dbefb8959ecfb7dd46 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sun, 14 Dec 2025 23:26:18 +0000 Subject: [PATCH 1/2] Initial plan From 1a4780d67996e904055c7f856de32efdcb287699 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sun, 14 Dec 2025 23:34:37 +0000 Subject: [PATCH 2/2] Update copilot-instructions.md with comprehensive project documentation Co-authored-by: mnaimfaizy <34773846+mnaimfaizy@users.noreply.github.com> --- .github/copilot-instructions.md | 965 +++++++++++++++++++++++++------- 1 file changed, 762 insertions(+), 203 deletions(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 828f625..987be95 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -4,30 +4,102 @@ **Code Executives** is an interactive programming education platform that transforms complex technical concepts into engaging visual learning experiences. The application uses React, TypeScript, and modern web technologies to create immersive educational content through 2D/3D visualizations. +### **Quick Reference** + +- **Technology Stack**: React 19 + TypeScript + Vite + Tailwind CSS 4.x + Three.js +- **Project Type**: Educational platform with 10 interactive learning modules +- **Architecture**: Feature-based organization with shared infrastructure +- **Testing**: Vitest + React Testing Library (76 tests across shared components) +- **Code Quality**: ESLint + Prettier + TypeScript strict mode +- **Dev Server**: `npm run dev` → http://localhost:5173 +- **Build**: `npm run build` (TypeScript + Vite) +- **Test**: `npm test` (watch mode) or `npm run test:run` (CI mode) + +### **10 Learning Modules** + +1. JavaScript Engine - V8 internals and execution flow +2. RxJS - Reactive programming with observables +3. Git - Version control with interactive visualizations +4. Data Structures - Arrays, trees, graphs with animations +5. React - Component patterns and hooks +6. Next.js - App Router and rendering strategies +7. Big-O Notation - Complexity analysis with gamification +8. Python - Language fundamentals and VM internals +9. System Design - Architecture patterns and scalability +10. TypeScript - Type system and advanced patterns + ## 🏗️ Architecture Principles ### **Core Technologies** - **Frontend**: React 19 + TypeScript + Vite - **Styling**: Tailwind CSS 4.x with utility-first approach -- **Routing**: React Router for SPA navigation +- **Routing**: React Router v7 for SPA navigation - **Visualizations**: SVG for 2D models, Three.js for 3D scenes - **Icons**: Lucide React for consistent iconography +- **Testing**: Vitest + React Testing Library +- **Code Editing**: Monaco Editor (for playground) +- **SEO**: @dr.pogodin/react-helmet for meta tags + +### **Architecture Patterns** + +- **Feature-Based Organization**: Each learning module is self-contained in `src/features/` +- **Shared Infrastructure**: Common utilities, components, and hooks in `src/shared/` +- **Lazy Loading**: All feature pages are code-split with `React.lazy()` +- **Error Boundaries**: Multiple levels (app, page, feature) for graceful error handling +- **Context Providers**: Theme, UI state, and app-level state management +- **Performance Monitoring**: Built-in performance dashboard for development +- **Analytics**: Optional Google Analytics integration via shared services ### **Project Structure Philosophy** ``` src/ -├── components/ # Reusable UI components -│ ├── models2d/ # 2D educational visualizations -│ ├── models3d/ # 3D interactive models -│ └── shared/ # Cross-module shared components -├── pages/ # Top-level page components -├── sections/ # Educational content modules -├── hooks/ # Custom React hooks for state management -├── types/ # TypeScript definitions -├── utils/ # Pure utility functions -└── three/ # Three.js models and scenes +├── features/ # Feature-based modules (10 learning modules) +│ ├── javascript/ # JavaScript Engine module +│ ├── rxjs/ # RxJS Reactive Programming module +│ ├── git/ # Git Tutorial module +│ ├── datastructures/ # Data Structures module +│ ├── react/ # React.js module +│ ├── nextjs/ # Next.js module +│ ├── bigo/ # Big-O Notation module +│ ├── python/ # Python Programming module +│ ├── systemdesign/ # System Design module +│ └── typescript/ # TypeScript module +│ └── [feature]/ +│ ├── components/ +│ │ ├── sections/ # Educational content sections +│ │ └── visualizations/ # 2D/3D interactive models +│ │ ├── 2d/ # SVG-based visualizations +│ │ └── 3d/ # Three.js models (optional) +│ ├── hooks/ # Feature-specific hooks +│ └── index.tsx # Feature entry point (Page component) +├── shared/ # Shared utilities across all features +│ ├── components/ # Reusable UI components +│ │ ├── feedback/ # ErrorBoundary, Toast, LoadingFallback, Skeleton +│ │ ├── navigation/ # Breadcrumbs, ProgressIndicator +│ │ ├── routing/ # SuspenseRoute +│ │ ├── accessibility/ # SkipLinks, ARIA utilities +│ │ ├── performance/ # PerformanceDashboard, PerformanceProfiler +│ │ ├── layout/ # Layout components +│ │ └── SEO/ # SEO component with react-helmet +│ ├── contexts/ # React Context providers (Theme, UI, App) +│ ├── services/ # Analytics, monitoring services +│ └── hooks/ # Shared custom hooks (useDebounce, useThrottle, etc.) +├── components/ # Global components (Header, Footer, Sidebar) +├── pages/ # Legacy page components (Home, About) +├── core/ # Core configuration +│ └── config/ # Environment and app configuration +├── data/ # Static data (problems, examples) +├── hooks/ # Legacy global hooks +├── types/ # TypeScript type definitions +├── utils/ # Pure utility functions (theme.ts) +├── three/ # Three.js engine and models +│ ├── core/ # Engine, types, animation scheduler +│ ├── models/ # 3D model implementations +│ └── react/ # React bridge (ThreeCanvas) +├── assets/ # Static assets (images, fonts) +└── test/ # Test utilities and setup ``` ## 🎨 Design System Guidelines @@ -42,84 +114,101 @@ Code Executives uses a comprehensive shared theme system located in `src/utils/t #### **Color Schemes by Section** +All 10 learning modules have dedicated color schemes in `src/utils/theme.ts`: + - **JavaScript**: Indigo/Purple/Blue theme (`theme.colors.javascript`) - **Git**: Orange/Red/Pink theme (`theme.colors.git`) - **Data Structures**: Blue/Indigo/Purple theme (`theme.colors.datastructures`) - **RxJS**: Purple/Violet/Indigo theme (`theme.colors.rxjs`) +- **React**: Blue/Indigo/Cyan theme (`theme.colors.react`) +- **Next.js**: Blue/Indigo/Cyan theme (`theme.colors.nextjs`) +- **Big-O**: Emerald/Teal/Cyan theme (`theme.colors.bigo`) +- **Python**: Blue/Indigo/Cyan theme (`theme.colors.python`) +- **System Design**: Blue/Indigo/Purple theme (`theme.colors.systemdesign`) +- **TypeScript**: Indigo/Purple/Blue theme (`theme.colors.typescript`) +- **Playground**: Blue/Indigo/Purple theme (`theme.colors.playground`) #### **Shared Components** -Use these pre-built components for consistency: +Use these pre-built shared components for consistency (located in `src/shared/components/`): ```typescript -// Layout Components -import SectionLayout from '../components/shared/SectionLayout'; -import ThemeCard from '../components/shared/ThemeCard'; -import NavigationCard from '../components/shared/NavigationCard'; -import StatsGrid from '../components/shared/StatsGrid'; -import CTASection from '../components/shared/CTASection'; - -// Usage Example - +// Feedback Components +import { ErrorBoundary } from '../shared/components/feedback/ErrorBoundary'; +import { Toast, ToastProvider } from '../shared/components/feedback/Toast'; +import { LoadingFallback } from '../shared/components/feedback/LoadingFallback'; +import { Skeleton } from '../shared/components/feedback/Skeleton'; + +// Navigation Components +import { Breadcrumbs } from '../shared/components/navigation/Breadcrumbs'; +import { ProgressIndicator } from '../shared/components/navigation/ProgressIndicator'; + +// Routing Components +import { SuspenseRoute } from '../shared/components/routing'; + +// Accessibility Components +import { SkipLinks } from '../shared/components/accessibility'; + +// Performance Components +import { PerformanceDashboard } from '../shared/components/performance'; + +// SEO Components +import { SEO } from '../shared/components/SEO'; + +// Context Providers +import { UIProvider, ThemeProvider, AppProvider } from '../shared/contexts'; + +// Usage Example with Feature Module + + + + + ``` #### **Standard Section Structure** -All sections should follow this consistent pattern: +All feature modules follow this consistent pattern using the features-based architecture: ```typescript -const SectionIntroduction: React.FC = () => { - // Hero content with title, description, and stats - const heroContent = ( -
-
-

Section Title

-

Description

-
- -
- ); - - // Main content with cards and information - const mainContent = ( - <> - ... - ... - - ); - - // Sidebar with navigation cards - const sidebarContent = ( - <> - - - - - ); +// src/features/[module]/index.tsx +import React from 'react'; +import { SEO } from '../../shared/components/SEO'; +import { ErrorBoundary } from '../../shared/components/feedback/ErrorBoundary'; +const ModulePage: React.FC = () => { return ( - <> - + - - +
+ {/* Hero Section */} +
+

Module Title

+

Description

+
+ + {/* Content Sections */} +
+ {/* Main Content */} +
+ {/* Educational content and visualizations */} +
+ + {/* Sidebar */} +
+ {/* Navigation cards, resources */} +
+
+
+ ); }; + +export default ModulePage; ``` ### **Component Patterns** @@ -169,9 +258,22 @@ const ctaClass = createCTAClass('indigo'); // Gradient background for CTAs #### **Adding New Sections** -When adding a new section, follow these steps: +When adding a new learning module, follow these steps: + +1. **Create Feature Directory Structure** in `src/features/[module]/`: + +```bash +src/features/[module]/ +├── components/ +│ ├── sections/ # Educational content components +│ └── visualizations/ # Interactive 2D/3D visualizations +│ ├── 2d/ # SVG-based components +│ └── 3d/ # Three.js models (optional) +├── hooks/ # Feature-specific custom hooks (optional) +└── index.tsx # Main page component (entry point) +``` -1. **Add Color Scheme** to `theme.colors` in `src/utils/theme.ts`: +2. **Add Color Scheme** to `theme.colors` in `src/utils/theme.ts`: ```typescript colors: { @@ -186,9 +288,27 @@ colors: { } ``` -2. **Create Section Introduction** using the shared components -3. **Update Navigation** in Header and Sidebar components -4. **Add Routing** in App.tsx +3. **Create Main Page Component** (`src/features/[module]/index.tsx`) +4. **Update Navigation** in `src/components/Header.tsx` and `src/components/Sidebar.tsx` +5. **Add Routing** in `src/App.tsx`: + +```typescript +// Import +const NewModulePage = lazy(() => import('./features/newmodule')); + +// Route + + + + } +/> +``` + +6. **Add Type Definitions** in `src/types/[module].ts` (if needed) +7. **Update README.md** with module information #### **Educational Content Structure** @@ -210,98 +330,28 @@ interface EducationalSection { ## 🧩 Component Development Guidelines -### **2D Visualization Components (src/components/models2d/)** +### **Feature Module Structure** -```typescript -interface Visualization2DProps { - isActive?: boolean; - animationStep?: number; - onStepChange?: (step: number) => void; - className?: string; -} - -// Example structure for 2D components -const MyVisualization2D: React.FC = ({ - isActive = false, - animationStep = 0, - onStepChange, - className = "" -}) => { - // Animation state management - const [currentStep, setCurrentStep] = useState(animationStep); - - // Interactive handlers - const handleElementClick = (elementId: string) => { - // Update animation state - // Trigger visual feedback - }; - - return ( -
- - {/* SVG content with animations */} - -
- ); -}; -``` - -### **Educational Section Components (src/sections/)** +All learning modules are organized under `src/features/[module]/`: ```typescript -interface SectionProps { - isActive?: boolean; - onNavigate?: (sectionId: string) => void; -} +// src/features/[module]/index.tsx - Main page component +import React from 'react'; +import { SEO } from '../../shared/components/SEO'; -const EducationalSection: React.FC = ({ isActive, onNavigate }) => { +const ModulePage: React.FC = () => { return ( -
-
- {/* Left: Educational content */} -
-

- Section Title -

-
- {/* Educational content */} -
-
- - {/* Right: Interactive visualization */} -
- -
- {/* Demo controls */} -
-
-
-
+ <> + + {/* Module content */} + ); }; -``` -### **Educational Content Structure** - -Each learning module follows this pattern: - -```typescript -interface EducationalSection { - title: string; - description: string; - visualization: React.ComponentType; - content: { - introduction: string; - keyPoints: string[]; - interactiveDemo?: React.ComponentType; - furtherReading?: string[]; - }; -} +export default ModulePage; ``` -## 🧩 Component Development Guidelines - -### **2D Visualization Components (src/components/models2d/)** +### **2D Visualization Components (src/features/[module]/components/visualizations/2d/)** ```typescript interface Visualization2DProps { @@ -337,7 +387,7 @@ const MyVisualization2D: React.FC = ({ }; ``` -### **Educational Section Components (src/sections/)** +### **Educational Section Components (src/features/[module]/components/sections/)** ```typescript interface SectionProps { @@ -354,7 +404,7 @@ const EducationalSection: React.FC = ({ isActive, onNavigate }) =>

Section Title

-
+
{/* Educational content */}
@@ -372,6 +422,48 @@ const EducationalSection: React.FC = ({ isActive, onNavigate }) => }; ``` +### **3D Visualization Components (src/three/models/)** + +For 3D visualizations using Three.js: + +1. Create model in `src/three/models/[Module]/[ModelName].ts` implementing `IModel` interface +2. Model must implement: `init(scene)`, `update(dt)`, `dispose()` +3. Use `ThreeCanvas` from `src/three/react/ThreeCanvas.tsx` to render in React +4. Expose imperative methods for UI interaction + +```typescript +// src/three/models/MyModule/MyModel3D.ts +import { IModel } from '../../core/types'; +import * as THREE from 'three'; + +export class MyModel3D implements IModel { + private mesh: THREE.Mesh | null = null; + + init(scene: THREE.Scene): void { + // Initialize 3D objects + const geometry = new THREE.BoxGeometry(1, 1, 1); + const material = new THREE.MeshStandardMaterial({ color: 0x0066ff }); + this.mesh = new THREE.Mesh(geometry, material); + scene.add(this.mesh); + } + + update(deltaTime: number): void { + // Update animation + if (this.mesh) { + this.mesh.rotation.y += deltaTime; + } + } + + dispose(): void { + // Cleanup + if (this.mesh) { + this.mesh.geometry.dispose(); + (this.mesh.material as THREE.Material).dispose(); + } + } +} +``` + ## 🎮 Interactive Features Standards ### **Demo Controls Pattern** @@ -410,28 +502,127 @@ const useVisualizationState = (initialState: VisualizationState) => { }; ``` -## 📚 Module-Specific Guidelines +## 🔧 Shared Infrastructure -### **Git Tutorial Module** +### **Context Providers** -- Focus on visual representation of Git operations -- Use consistent color coding: green for staged, blue for committed, red for conflicts -- Animate file state transitions clearly -- Include realistic file/folder structures in examples +The application uses React Context for global state management: -### **JavaScript Engine Module** +```typescript +// From src/shared/contexts +import { AppProvider } from './shared/contexts/AppContext'; // App-level state +import { ThemeProvider } from './shared/contexts/ThemeContext'; // Theme preferences +import { UIProvider } from './shared/contexts/UIContext'; // UI state (sidebar, modals) + +// Usage in App.tsx + + + + {/* Your app */} + + + +``` + +### **Services** -- Emphasize execution flow with call stack visualizations -- Show memory allocation patterns clearly -- Use consistent metaphors (restaurant kitchen for event loop, library for memory heap) -- Include performance implications in explanations +Shared services for cross-cutting concerns: -### **RxJS Module** +```typescript +// Analytics Service (src/shared/services/analytics) +import analyticsService from './shared/services/analytics'; -- Use marble diagrams extensively -- Show data flow through operators visually -- Include interactive stream builders -- Demonstrate error handling patterns +// Initialize in App.tsx +analyticsService.initialize(googleAnalyticsId); + +// Track page views +analyticsService.trackPageView('/module-name'); + +// Track custom events +analyticsService.trackEvent('feature_used', { feature: 'visualization' }); +``` + +### **Environment Configuration** + +```typescript +// src/core/config/env.ts +import { env } from './core/config/env'; + +// Available environment variables +env.enableAnalytics // boolean +env.googleAnalyticsId // string | undefined +env.isDevelopment // boolean +env.isProduction // boolean + +// Access in components +import.meta.env.DEV // Vite development mode +import.meta.env.PROD // Vite production mode +``` + +## 📚 Module-Specific Guidelines + +### **All 10 Learning Modules** + +The application includes these complete learning modules: + +1. **JavaScript Engine** (`src/features/javascript/`) + - V8 runtime internals and execution flow + - Call stack, memory heap, event loop visualizations + - Memory management and garbage collection + +2. **RxJS Reactive Programming** (`src/features/rxjs/`) + - Observable streams and operators + - Marble diagrams and data flow visualizations + - Error handling patterns + +3. **Git Tutorial** (`src/features/git/`) + - Three-tree model and object model + - Branching, merging, and collaboration workflows + - Use green for staged, blue for committed, red for conflicts + +4. **Data Structures** (`src/features/datastructures/`) + - Linear structures, hash tables, trees, graphs + - Interactive visualizations and algorithm animations + - LeetCode-style practice problems + +5. **React.js** (`src/features/react/`) + - React fundamentals and component patterns + - Hooks, context, and state management + - Performance optimization techniques + +6. **Next.js** (`src/features/nextjs/`) + - App Router architecture and file-system routing + - Rendering strategies (SSR, SSG, CSR, ISR) + - Server/Client components and data fetching + +7. **Big-O Notation** (`src/features/bigo/`) + - Algorithmic complexity analysis + - Interactive complexity comparisons + - Visual metaphors and gamification + +8. **Python Programming** (`src/features/python/`) + - Zen of Python and execution model + - Memory management and GIL + - 3D visualizations of Python VM + +9. **System Design** (`src/features/systemdesign/`) + - System architecture patterns + - Scalability and reliability concepts + - Real-world case studies + +10. **TypeScript** (`src/features/typescript/`) + - Type system fundamentals + - Advanced types and generics + - Best practices and patterns + +### **Visualization Guidelines by Module** + +- **Git**: Use consistent color coding (green=staged, blue=committed, red=conflicts) +- **JavaScript**: Use kitchen metaphor for event loop, library for memory heap +- **RxJS**: Use marble diagrams extensively for data streams +- **Data Structures**: Show step-by-step algorithm execution +- **Big-O**: Use visual metaphors (teleporter, librarian, conveyor belt) +- **Python**: 3D models for VM internals and memory profiler ## 🚨 Code Quality Standards @@ -441,30 +632,100 @@ const useVisualizationState = (initialState: VisualizationState) => { - Use strict type checking (`strict: true` in tsconfig) - Prefer interfaces over types for object shapes - Use generic types for reusable components +- No implicit `any` types allowed +- Import types with `import type` when possible + +### **ESLint Configuration** + +The project uses: +- `@typescript-eslint` for TypeScript-specific rules +- `eslint-plugin-react` and `eslint-plugin-react-hooks` for React best practices +- `eslint-plugin-import` for import organization +- `eslint-config-prettier` to avoid conflicts with Prettier + +Run `npm run lint` to check for issues, `npm run lint:fix` to auto-fix. ### **Performance Guidelines** -- Lazy load heavy components with `React.lazy()` -- Optimize SVG animations with `will-change` CSS property -- Use `useMemo` and `useCallback` for expensive computations -- Minimize re-renders with proper dependency arrays +- **Code Splitting**: Lazy load heavy components with `React.lazy()` +- **SVG Optimization**: Use `will-change` CSS property for animations +- **Memoization**: Use `useMemo` and `useCallback` for expensive computations +- **Re-render Prevention**: Proper dependency arrays in hooks +- **Bundle Analysis**: Available via `rollup-plugin-visualizer` in build +- **Performance Monitoring**: Use `PerformanceDashboard` in development ### **Accessibility Standards** - All interactive elements must be keyboard accessible -- Use semantic HTML elements +- Use semantic HTML elements (` + + +``` + +5. **Include Educational Tooltips**: +```typescript +Explanation of what this element represents +``` + +### **Using Shared Hooks** + +The project includes several custom hooks in `src/shared/hooks/`: + +```typescript +// Debounce user input +import { useDebounce } from '../../shared/hooks/useDebounce'; +const debouncedValue = useDebounce(searchTerm, 300); + +// Throttle frequent events +import { useThrottle } from '../../shared/hooks/useThrottle'; +const throttledValue = useThrottle(scrollPosition, 100); + +// Detect reduced motion preference +import { useReducedMotion } from '../../shared/hooks/useReducedMotion'; +const prefersReducedMotion = useReducedMotion(); + +// Keyboard navigation +import { useKeyboardNavigation } from '../../shared/hooks/useKeyboardNavigation'; +const { activeIndex, handleKeyDown } = useKeyboardNavigation(items.length); +``` ### **Styling Best Practices** @@ -522,23 +963,91 @@ const cardStyles = ['bg-white', 'border border-gray-200', 'rounded-xl shadow-sm' - **TypeScript Errors**: Check interface definitions and prop passing - **Responsive Issues**: Test with browser dev tools device simulation - **Build Errors**: Ensure all imports are correct and files exist +- **Lazy Loading Errors**: Check that default exports are used in lazy-loaded components +- **Theme Issues**: Verify color scheme exists in `src/utils/theme.ts` ### **Development Tools** -- **Vite Dev Server**: Hot reload for rapid development -- **React Developer Tools**: Component debugging +- **Vite Dev Server**: Hot reload for rapid development (http://localhost:5173) +- **React Developer Tools**: Component debugging and profiler - **TypeScript Compiler**: Type checking and error reporting - **Browser Dev Tools**: Performance profiling and debugging +- **Performance Dashboard**: Built-in dashboard in dev mode (bottom-right corner) +- **Vitest UI**: Interactive test runner (`npm run test:ui`) + +### **Debugging Strategies** + +1. **Component Issues**: + - Add `console.log` or use React DevTools + - Check prop types and interfaces + - Verify component is wrapped in ErrorBoundary + +2. **Performance Issues**: + - Open Performance Dashboard in dev mode + - Use React DevTools Profiler + - Check for unnecessary re-renders + - Verify proper memoization + +3. **Build Issues**: + - Check TypeScript errors: `npm run build` + - Clear node_modules and reinstall: `rm -rf node_modules && npm install` + - Check for circular dependencies + +4. **Test Failures**: + - Run single test file: `npm test -- Component.test.tsx` + - Use `test.only()` to isolate failing test + - Check for missing test setup or mocks + +## ⚠️ Common Pitfalls to Avoid + +### **Don'ts** + +- ❌ Don't use `dark:` prefixed Tailwind classes (light mode only) +- ❌ Don't create components in wrong directory (use features-based structure) +- ❌ Don't skip TypeScript types (explicit typing required) +- ❌ Don't ignore ESLint warnings (fix or justify them) +- ❌ Don't use inline styles (use Tailwind utilities) +- ❌ Don't forget to lazy load feature pages +- ❌ Don't skip ErrorBoundary wrappers +- ❌ Don't forget to update navigation when adding modules +- ❌ Don't commit without running tests +- ❌ Don't use any type (be explicit) + +### **Do's** + +- ✅ Use feature-based directory structure +- ✅ Wrap pages in ErrorBoundary and SEO components +- ✅ Use shared components and hooks when available +- ✅ Follow established patterns for consistency +- ✅ Write tests for new components and hooks +- ✅ Use semantic HTML and ARIA labels +- ✅ Optimize for accessibility and performance +- ✅ Add proper TypeScript types and interfaces +- ✅ Use lazy loading for heavy components +- ✅ Test responsive design on multiple breakpoints ## 📖 Resources and References ### **Key Documentation** -- [React Documentation](https://react.dev/) -- [TypeScript Handbook](https://www.typescriptlang.org/docs/) -- [Tailwind CSS Documentation](https://tailwindcss.com/docs) -- [Three.js Documentation](https://threejs.org/docs/) -- [Vite Documentation](https://vitejs.dev/) +- [React Documentation](https://react.dev/) - React 19 features and hooks +- [TypeScript Handbook](https://www.typescriptlang.org/docs/) - Type system reference +- [Tailwind CSS Documentation](https://tailwindcss.com/docs) - Utility classes and configuration +- [Three.js Documentation](https://threejs.org/docs/) - 3D visualization library +- [Vite Documentation](https://vitejs.dev/) - Build tool and dev server +- [Vitest Documentation](https://vitest.dev/) - Testing framework +- [React Router Documentation](https://reactrouter.com/) - Routing library +- [React Testing Library](https://testing-library.com/react) - Component testing + +### **Project-Specific Documentation** + +- **README.md**: Comprehensive project overview and setup +- **docs/** directory: Implementation plans and guides for each module + - `Next.js-Implementation-Plan.md` + - `Data-Structures-Implementation-Plan.md` + - `Big-O-Notation-Implementation-Plan.md` + - `Python-Module-Implementation-Plan.md` + - And more... ### **Educational Content Guidelines** @@ -546,7 +1055,57 @@ const cardStyles = ['bg-white', 'border border-gray-200', 'rounded-xl shadow-sm' - Use progressive disclosure (simple to complex) - Include real-world examples and use cases - Provide multiple learning paths for different skill levels +- Add interactive visualizations for complex concepts +- Include step-by-step animations for algorithms +- Use consistent metaphors across related concepts +- Provide practice problems and solutions + +### **Component Libraries** + +- **Lucide React**: https://lucide.dev/ - Icon library +- **React Helmet**: https://github.com/dr-pogodin/react-helmet - SEO and meta tags + +### **Best Practices Resources** + +- [React Best Practices 2024](https://react.dev/learn) +- [TypeScript Best Practices](https://www.typescriptlang.org/docs/handbook/declaration-files/do-s-and-don-ts.html) +- [Accessibility Guidelines (WCAG 2.1)](https://www.w3.org/WAI/WCAG21/quickref/) +- [Performance Best Practices](https://web.dev/performance/) --- +## 📋 Summary + **Remember**: This project is educational first - prioritize clarity, interactivity, and visual appeal over complex features. Every component should contribute to the learning experience. + +### **Key Principles** + +1. **Feature-Based Architecture**: Self-contained modules in `src/features/` +2. **Shared Infrastructure**: Reusable components, hooks, and services in `src/shared/` +3. **TypeScript Strict Mode**: Explicit types required for all code +4. **Accessibility First**: WCAG 2.1 AA compliance with semantic HTML +5. **Performance Optimized**: Lazy loading, memoization, code splitting +6. **Test Coverage**: Comprehensive tests with Vitest +7. **Light Mode Only**: No dark theme support +8. **Educational Focus**: Clear explanations with interactive visualizations + +### **When Adding New Code** + +1. Follow features-based directory structure +2. Use TypeScript with explicit types +3. Add tests alongside components +4. Use shared components and hooks +5. Ensure accessibility compliance +6. Optimize for performance +7. Run linting and tests before committing +8. Update documentation as needed + +### **Quick Commands** + +```bash +npm run dev # Start development +npm run build # Build for production +npm test # Run tests +npm run lint # Check code quality +npm run format # Format code +```