feat: Introduce 'Static vs Instance' module, overhaul project README, and configure Vite for GitHub Pages deployment.

PramithaMJ · PramithaMJ · commit 5eb16eb56ca4 · 2026-02-02T01:59:19.000+05:30
diff --git a/README.md b/README.md
@@ -1,73 +1,167 @@
-# React + TypeScript + Vite
+# Java Engineering Masterclass 🚀
 
-This template provides a minimal setup to get React working in Vite with HMR and some ESLint rules.
+An interactive, production-grade React application for mastering advanced Java/JVM concepts through visual simulations and deep-dive theory.
 
-Currently, two official plugins are available:
+![React](https://img.shields.io/badge/React-19-blue?logo=react)
+![TypeScript](https://img.shields.io/badge/TypeScript-5.9-blue?logo=typescript)
+![Vite](https://img.shields.io/badge/Vite-7-purple?logo=vite)
+![License](https://img.shields.io/badge/License-MIT-green)
 
-- [@vitejs/plugin-react](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react) uses [Babel](https://babeljs.io/) (or [oxc](https://oxc.rs) when used in [rolldown-vite](https://vite.dev/guide/rolldown)) for Fast Refresh
-- [@vitejs/plugin-react-swc](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react-swc) uses [SWC](https://swc.rs/) for Fast Refresh
+## 🎯 Features
 
-## React Compiler
+### Interactive Simulators
 
-The React Compiler is not enabled on this template because of its impact on dev & build performances. To add it, see [this documentation](https://react.dev/learn/react-compiler/installation).
+| Module | Description | Visualization |
+|--------|-------------|---------------|
+| **Garbage Collection** | Eden, Survivor, Old Gen memory pools | Object allocation & GC cycles |
+| **Concurrency** | Monitor locks, Entry/Wait sets | Thread state transitions |
+| **JIT Compilation** | Tiered compilation (Interpreted → C1 → C2) | Profiling & optimization |
+| **Java Memory Model** | CPU caches, Main Memory, Volatile | Cache coherence & visibility |
+| **Static vs Instance** | Metaspace vs Heap memory layout | Static field sharing |
 
-## Expanding the ESLint configuration
+### Educational Theory
 
-If you are developing a production application, we recommend updating the configuration to enable type-aware lint rules:
+Each module includes comprehensive "Engineer's Guide" content covering:
+- Under-the-hood JVM internals
+- Best practices and anti-patterns
+- Thread safety considerations
+- Performance implications
 
-```js
-export default defineConfig([
-  globalIgnores(['dist']),
-  {
-    files: ['**/*.{ts,tsx}'],
-    extends: [
-      // Other configs...
+## 🏗️ Architecture
 
-      // Remove tseslint.configs.recommended and replace with this
-      tseslint.configs.recommendedTypeChecked,
-      // Alternatively, use this for stricter rules
-      tseslint.configs.strictTypeChecked,
-      // Optionally, add this for stylistic rules
-      tseslint.configs.stylisticTypeChecked,
+Built following **SOLID principles** with a modular, scalable architecture:
 
-      // Other configs...
-    ],
-    languageOptions: {
-      parserOptions: {
-        project: ['./tsconfig.node.json', './tsconfig.app.json'],
-        tsconfigRootDir: import.meta.dirname,
-      },
-      // other options...
-    },
-  },
-])
 ```
+src/
+├── components/           # Reusable UI components
+│   ├── Layout/          # Header, Layout wrapper
+│   ├── UI/              # Button, Console, MemoryBlock
+│   └── Hub/             # Module selection grid
+├── features/            # Feature modules (one per topic)
+│   ├── gc/              # Garbage Collection
+│   ├── threads/         # Concurrency
+│   ├── jit/             # JIT Compilation
+│   ├── jmm/             # Java Memory Model
+│   └── static/          # Static vs Instance
+├── hooks/               # Custom React hooks (simulation logic)
+├── contexts/            # React Context providers
+├── types/               # TypeScript type definitions
+└── App.tsx              # Root application component
+```
+
+## 🚀 Getting Started
+
+### Prerequisites
+
+- Node.js 18+ 
+- npm or yarn
+
+### Installation
+
+```bash
+# Clone the repository
+git clone https://github.com/pramithamj/java-masterclass.git
+cd java-masterclass
+
+# Install dependencies
+npm install
+
+# Start development server
+npm run dev
+```
+
+Open [http://localhost:5173](http://localhost:5173) in your browser.
 
-You can also install [eslint-plugin-react-x](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-x) and [eslint-plugin-react-dom](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-dom) for React-specific lint rules:
-
-```js
-// eslint.config.js
-import reactX from 'eslint-plugin-react-x'
-import reactDom from 'eslint-plugin-react-dom'
-
-export default defineConfig([
-  globalIgnores(['dist']),
-  {
-    files: ['**/*.{ts,tsx}'],
-    extends: [
-      // Other configs...
-      // Enable lint rules for React
-      reactX.configs['recommended-typescript'],
-      // Enable lint rules for React DOM
-      reactDom.configs.recommended,
-    ],
-    languageOptions: {
-      parserOptions: {
-        project: ['./tsconfig.node.json', './tsconfig.app.json'],
-        tsconfigRootDir: import.meta.dirname,
-      },
-      // other options...
-    },
-  },
-])
+### Build for Production
+
+```bash
+npm run build
+npm run preview    # Preview production build locally
 ```
+
+## 🌐 Deployment
+
+### GitHub Pages
+
+The app is configured for GitHub Pages deployment:
+
+1. Build the project: `npm run build`
+2. Push to your repository
+3. Enable GitHub Pages in repository settings (deploy from `gh-pages` branch or `/docs` folder)
+
+> **Note**: The `base` path in `vite.config.ts` must match your repository name.
+
+## 📚 Module Details
+
+### Garbage Collection Simulator
+
+Visualize the **Generational Hypothesis** in action:
+- **Eden Space**: Where new objects are allocated
+- **Survivor Space**: Objects that survive Minor GC
+- **Old Generation**: Long-lived objects (tenured)
+- Trigger Minor GC and Full GC to see object lifecycle
+
+### Concurrency Simulator
+
+Understand Java's **Monitor Lock** mechanism:
+- See threads competing for synchronized blocks
+- Watch Entry Set (blocked) and Running states
+- Visualize lock acquisition and release
+
+### JIT Compilation Simulator
+
+Watch code get "hot" and tiered compilation kick in:
+- **Interpreted**: Initial slow execution
+- **C1 Compiler**: Quick compilation, basic optimizations
+- **C2 Compiler**: Aggressive optimization (inlining, escape analysis)
+
+### Java Memory Model Lab
+
+Understand **visibility** and **happens-before**:
+- CPU L1 caches vs Main Memory
+- Volatile writes flush to memory
+- Non-volatile reads may see stale data
+
+### Static vs Instance Lab
+
+Visualize where static and instance members live:
+- **Metaspace**: Class-level static fields (shared)
+- **Heap**: Per-instance fields (unique per object)
+- See how static changes affect ALL instances
+
+## 🛠️ Technology Stack
+
+- **React 19** - UI framework with hooks
+- **TypeScript 5.9** - Type safety
+- **Vite 7** - Fast build tool with HMR
+- **CSS Modules** - Scoped styling
+- **ESLint** - Code quality
+
+## 📝 Design Principles
+
+1. **Single Responsibility (SRP)**: Each component/hook has one clear purpose
+2. **Open/Closed (OCP)**: Easy to add new modules without modifying core
+3. **Dependency Inversion (DIP)**: Contexts provide injectable dependencies
+4. **Interface Segregation (ISP)**: Small, focused type interfaces
+
+## 🤝 Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/AmazingFeature`)
+3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
+4. Push to the branch (`git push origin feature/AmazingFeature`)
+5. Open a Pull Request
+
+## 📄 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## 🙏 Acknowledgments
+
+- Inspired by the need for better JVM education tools
+- Built with modern React best practices
+- Designed for developers learning advanced Java concepts
+
+---
diff --git a/src/App.tsx b/src/App.tsx
@@ -5,7 +5,7 @@
 
 import { NavigationProvider, ConsoleProvider, useNavigation, isModuleView } from './contexts';
 import { Layout, ModuleHub, ModuleTabs } from './components';
-import { GCModule, ThreadsModule, JITModule, JMMModule } from './features';
+import { GCModule, ThreadsModule, JITModule, JMMModule, StaticModule } from './features';
 import type { ModuleId } from './types';
 
 /**
@@ -25,6 +25,7 @@ function ModuleRenderer() {
     threads: ThreadsModule,
     jit: JITModule,
     jmm: JMMModule,
+    static: StaticModule,
   };
 
   const ModuleComponent = moduleComponents[currentView];
diff --git a/src/components/Hub/ModuleHub.tsx b/src/components/Hub/ModuleHub.tsx
@@ -4,7 +4,7 @@
  */
 
 import { useNavigation } from '../../contexts';
-import { MODULE_REGISTRY, type ModuleId } from '../../types';
+import { MODULE_REGISTRY } from '../../types';
 import styles from './ModuleHub.module.css';
 
 export function ModuleHub() {
diff --git a/src/features/threads/ThreadsSimulator.tsx b/src/features/threads/ThreadsSimulator.tsx
@@ -9,7 +9,7 @@ import { Button, Console } from '../../components';
 import styles from './ThreadsSimulator.module.css';
 
 export function ThreadsSimulator() {
-    const { threads, lock, blockedQueue, runningQueue, spawnThread } = useThreadSimulator();
+    const { threads, lock, spawnThread } = useThreadSimulator();
     const { logs } = useModuleConsole('threads');
 
     // Filter active (non-terminated) threads for display
diff --git a/src/hooks/useThreadSimulator.ts b/src/hooks/useThreadSimulator.ts
@@ -72,26 +72,6 @@ export function useThreadSimulator(): IUseThreadSimulator {
         });
     }, [log]);
 
-    const acquireLock = useCallback((thread: IThread) => {
-        const updatedThread = { ...thread, state: 'running' as const };
-
-        log(`Thread-${thread.id} acquired Lock. Executing...`, 'success');
-
-        // Schedule release
-        lockTimeoutRef.current = setTimeout(() => {
-            releaseLock(updatedThread);
-        }, THREAD_CONSTANTS.LOCK_HOLD_DURATION_MS);
-
-        setState((prev) => ({
-            ...prev,
-            threads: prev.threads.map((t) =>
-                t.id === thread.id ? updatedThread : t
-            ),
-            lock: { isLocked: true, owner: updatedThread },
-            runningQueue: [updatedThread],
-        }));
-    }, [log, releaseLock]);
-
     const spawnThread = useCallback(() => {
         const newThread: IThread = {
             id: nextThreadId.current++,
diff --git a/vite.config.ts b/vite.config.ts
@@ -4,4 +4,8 @@ import react from '@vitejs/plugin-react'
 // https://vite.dev/config/
 export default defineConfig({
   plugins: [react()],
+  // Base path for GitHub Pages deployment
+  // Change this to match your repository name
+  base: '/java-masterclass/',
 })
+
