nextrush 1.5.0 → 2.0.1

package/README.md

@@ -1,414 +1,1356 @@
-# 🦊 NextRush - Learning Project
-
 <div align="center">
 
-[![Learning Project](https://img.shields.io/badge/Status-Learning%20Project-orange.svg)](https://github.com/0xTanzim/nextRush)
-[![NPM Version](https://img.shields.io/npm/v/nextrush.svg)](https://www.npmjs.com/package/nextrush)
-[![TypeScript](https://img.shields.io/badge/TypeScript-Learning-blue.svg)](https://www.typescriptlang.org/)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+# 🚀 NextRush v2
 
-**🎓 My first web framework - Built for learning, not production**
+**Modern, Type-Safe Web Framework for Node.js**
 
-</div>
+_Koa-style Context • Express-inspired API • Enterprise Features Built-in_
+
+[![npm version](https://img.shields.io/npm/v/nextrush?color=brightgreen&style=for-the-badge)](https://www.npmjs.com/package/nextrush)
+[![Node.js](https://img.shields.io/badge/Node.js-20+-339933?style=for-the-badge&logo=node.js&logoColor=white)](https://nodejs.org/)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.8+-3178C6?style=for-the-badge&logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
+[![License](https://img.shields.io/badge/License-MIT-yellow?style=for-the-badge)](LICENSE)
+[![Tests](https://img.shields.io/badge/Tests-1461%20Passing-brightgreen?style=for-the-badge)](https://github.com/0xTanzim/nextrush)
+[![Zero Dependencies](https://img.shields.io/badge/Dependencies-0-brightgreen?style=for-the-badge)](https://github.com/0xTanzim/nextrush)
 
 ```typescript
 import { createApp } from 'nextrush';
 
 const app = createApp();
 
-app.get('/', (req, res) => {
-  res.json({ message: 'Hello NextRush!' });
+app.get('/hello', async ctx => {
+  ctx.json({ message: 'Welcome to NextRush v2! 🎉' });
 });
 
 app.listen(3000);
-// 🚀 Express.js-compatible API with zero dependencies
+// Server running at http://localhost:3000
 ```
 
-## ⚠️ **Learning Project Notice**
+[**📖 Documentation**](./docs)  • [**🚀 Quick Start**](#-quick-start) • [**💡 Why NextRush?**](#-why-nextrush-v2)
 
-This is my **first attempt** at building a Node.js web framework. Created for **educational purposes only**.
-
-**🚨 For Production**: Use [Express.js](https://expressjs.com/), [Fastify](https://fastify.dev/), or [Koa](https://koajs.com/) instead.
+</div>
 
-## 🏆 **Latest Benchmark Results** _(July 2025)_
+---
 
-> **Ultimate Fox Test** - Maximum RPS testing with Apache Bench on Intel i5-8300H, 14GB RAM
+## 💡 Philosophy
 
-### **🥇 Overall Performance Rankings:**
+**NextRush v2 combines the best of three worlds**: Koa's elegant async context pattern, Express's intuitive helper methods, and Fastify's performance optimizations—all with **enterprise-grade features built directly into the core**.
 
-| Rank | Framework    | **Peak RPS** | **Best At**     | **Avg Latency** |
-| ---- | ------------ | ------------ | --------------- | --------------- |
-| 🥇   | **Fastify**  | **9,491**    | Low concurrency | **5.3ms**       |
-| 🥈   | **Express**  | **7,146**    | All loads       | **14.0ms**      |
-| 🥉   | **NextRush** | **5,784**    | Medium loads    | **34.6ms**      |
+Unlike other frameworks that require dozens of plugins for production use, NextRush v2 includes security middleware, validation, templating, WebSocket support, and advanced logging out of the box. Choose your preferred API style: convenience methods, Express-like helpers, or Fastify-style configuration.
 
-### **📊 Detailed Performance by Connection Count:**
+**Built for teams that value type safety, developer experience, and production readiness without the plugin fatigue.**
 
-#### **50 Connections (Light Load):**
+---
 
-| Framework    | RPS       | Latency | Status        |
-| ------------ | --------- | ------- | ------------- |
-| **Fastify**  | **9,491** | 5.3ms   | 🏆 **Winner** |
-| **Express**  | **6,934** | 7.2ms   | 🥈 Good       |
-| **NextRush** | **5,612** | 8.9ms   | 🥉 Decent     |
+## 🎯 Zero Dependencies Philosophy
 
-#### **100 Connections (Medium Load):**
+**NextRush v2 is built with ZERO runtime dependencies.** Every feature—from routing to WebSocket support—is implemented using only Node.js core modules.
 
-| Framework    | RPS       | Latency | Status        |
-| ------------ | --------- | ------- | ------------- |
-| **Express**  | **7,146** | 14.0ms  | 🏆 **Winner** |
-| **Fastify**  | **9,154** | 10.9ms  | 🥈 Close      |
-| **NextRush** | **5,669** | 17.6ms  | 🥉 Stable     |
+### Why Zero Dependencies?
 
-#### **200 Connections (High Load):**
+- **🔒 Security** - No third-party vulnerabilities in your supply chain
+- **⚡ Faster Installs** - No dependency resolution, instant setup
+- **🛡️ Stability** - No breaking changes from external packages
+- **🔍 Full Control** - Every line of code is maintainable and auditable
+- **🚀 Performance** - Optimized for Node.js internals, no abstraction overhead
 
-| Framework    | RPS       | Latency | Status        |
-| ------------ | --------- | ------- | ------------- |
-| **Fastify**  | **9,405** | 21.3ms  | 🏆 **Winner** |
-| **Express**  | **6,890** | 29.0ms  | � Good        |
-| **NextRush** | **5,784** | 34.6ms  | 🥉 **Peak**   |
+```bash
+# Check it yourself! Only devDependencies, ZERO runtime deps
+npm ls --production --depth=0
+# Result: (empty)
+```
 
-#### **500+ Connections (Extreme Load):**
+**Every framework claims to be "lightweight." NextRush v2 proves it.**
 
-| Framework    | RPS       | Latency | Performance |
-| ------------ | --------- | ------- | ----------- |
-| **Fastify**  | **8,598** | 58.2ms  | Declining   |
-| **Express**  | **7,068** | 70.7ms  | Consistent  |
-| **NextRush** | **5,539** | 90.3ms  | Dropping    |
+| Framework       | Runtime Dependencies                 |
+| --------------- | ------------------------------------ |
+| **NextRush v2** | **0** ⭐                             |
+| Express         | 34+ packages                         |
+| Koa             | 0 (but needs plugins for everything) |
+| Fastify         | 20+ packages                         |
+| Hapi            | 50+ packages                         |
 
-### **🎯 Performance Analysis:**
+> **Built-in features without the dependency hell.** Security, validation, WebSocket, templates, logging, CQRS—all implemented with pure Node.js.
 
-#### **🚀 Fastify Strengths:**
+---
 
-- **Dominates low concurrency** (50-200 connections)
-- **Excellent latency** across all loads
-- **9.5K RPS peak** - industry-leading performance
+## 🎯 Why NextRush v2?
 
-#### **💪 Express Strengths:**
+NextRush v2 represents the evolution of Node.js web frameworks, synthesizing proven patterns from Express, Koa, and Fastify into a unified, type-safe framework with enterprise features integrated at the core.
 
-- **Most consistent** across all connection counts
-- **Handles high loads well** (500+ connections)
-- **Proven stability** under stress
+### 🏆 Three API Styles, One Framework
 
-#### **🎓 NextRush Analysis:**
+| **Convenience API** | **Enhanced API** | **Configuration API** |
+| ------------------- | ---------------- | --------------------- |
+| `ctx.json()`        | `ctx.res.json()` | `{ handler, schema }` |
+| Clean & simple      | Express-inspired | Fastify-style         |
+| **Recommended**     | Familiar pattern | Advanced use cases    |
 
-- **Best at 200 connections** (architectural sweet spot)
-- **Competitive performance** for a learning project
-- **Room for optimization** - performance gap shows learning opportunities
+### ⚡ Performance That Scales
 
-### **� Key Performance Insights:**
+- **Zero Dependencies** - Pure Node.js core, no third-party overhead
+- **13,261 RPS Average** - Competitive with established frameworks
+- **Optimized Router** - O(1) static path lookup, pre-compiled routes
+- **Memory Efficient** - ~60KB baseline, smallest footprint in class
+- **Smart Caching** - Template caching, efficient buffer management
+- **No Supply Chain Tax** - Every feature optimized for Node.js internals
 
-- **NextRush achieves 61% of Fastify's peak performance** - respectable for first framework
-- **Zero memory leaks** detected across all test scenarios
-- **Performance gap mainly due to** architecture complexity vs. mature optimization
-- **Learning-focused development** prioritized features over raw speed
-- **Plugin architecture overhead** impacts performance but provides flexibility
+### 🛡️ Enterprise Features Built-In
 
-### **🔬 Test Configuration:**
+Unlike other frameworks requiring extensive plugin ecosystems, NextRush v2 includes production-ready features in the core:
 
-- **Tool**: Apache Bench (ab) for accurate RPS measurement
-- **Requests**: 10,000 per test for statistical significance
-- **Duration**: 60-second timeout per test
-- **Hardware**: Intel i5-8300H, 14GB RAM, Ubuntu 25.04
-- **Node.js**: v24.4.1 (latest LTS)
-- **Methodology**: Multiple runs, averaged results
+```typescript
+const app = createApp();
 
-## ✨ **What Makes NextRush Special**
+// Security middleware (CORS, Helmet, Rate Limiting)
+app.use(app.cors({ origin: ['https://example.com'] }));
+app.use(app.helmet({ xssFilter: true }));
+app.use(app.rateLimiter({ max: 100, windowMs: 15 * 60 * 1000 }));
 
-### **🔥 Built-in Features Comparison:**
+// Smart body parser with auto-detection
+app.use(app.smartBodyParser({ maxSize: 10 * 1024 * 1024 }));
 
-| Feature                     | NextRush | Express | Fastify | Dependencies Needed          |
-| --------------------------- | -------- | ------- | ------- | ---------------------------- |
-| **Zero Dependencies**       | ✅       | ❌      | ❌      | NextRush: 0, Others: 10+     |
-| **Express Compatible**      | ✅       | ✅      | ❌      | Drop-in replacement          |
-| **TypeScript First**        | ✅       | ⚠️      | ✅      | Built-in vs. @types packages |
-| **Built-in Body Parser**    | ✅       | ❌      | ✅      | express requires body-parser |
-| **Built-in File Uploads**   | ✅       | ❌      | ❌      | express requires multer      |
-| **Built-in WebSocket**      | ✅       | ❌      | ❌      | Others require socket.io     |
-| **Built-in Templates**      | ✅       | ❌      | ❌      | Others require view engines  |
-| **Built-in Security**       | ✅       | ❌      | ❌      | Others require helmet + more |
-| **Built-in Rate Limiting**  | ✅       | ❌      | ❌      | express-rate-limit needed    |
-| **Built-in Authentication** | ✅       | ❌      | ❌      | passport + sessions needed   |
-| **API Documentation**       | ✅       | ❌      | ❌      | swagger packages needed      |
-| **Performance Ranking**     | 3rd      | 2nd     | 1st     | Speed vs. Features trade-off |
+// Advanced validation & sanitization
+const userData = validateRequest(ctx, userSchema);
+const cleanData = sanitizeInput(userData);
 
-### **🔥 Core Features:**
+// Custom error classes with contextual information
+throw new NotFoundError('User not found', {
+  userId: ctx.params.id,
+  suggestion: 'Verify the user ID is correct',
+});
 
-#### **🛡️ Security & Validation:**
+// Event-driven architecture (Simple + CQRS patterns)
+await app.events.emit('user.registered', { userId: user.id });
+await app.eventSystem.dispatch({ type: 'CreateUser', data: {...} });
 
-- **Input Validation** - Built-in request validation with custom rules
-- **XSS Protection** - Automatic cross-site scripting prevention
-- **SQL Injection Prevention** - Query sanitization and parameterization
-- **CORS Management** - Flexible cross-origin resource sharing
-- **Rate Limiting** - Configurable request throttling per IP/user
+// Template engine with automatic XSS protection
+await ctx.render('profile.html', { user, isAdmin });
 
-#### **📁 File Handling:**
+// WebSocket support with room management
+wsApp.ws('/chat', socket => {
+  socket.join('room1');
+  socket.onMessage(data => wsApp.wsBroadcast(data, 'room1'));
+});
 
-- **Static File Serving** - High-performance with compression & caching
-- **File Uploads** - Multipart form data with size limits
-- **Download Management** - Secure file downloads with access control
-- **Image Processing** - Basic resize and format conversion
+// Structured logging with multiple transports
+ctx.logger.info('User action', { userId, action });
 
-#### **🌐 Real-time Features:**
+// Dependency injection container
+const service = container.resolve('UserService');
+```
 
-- **WebSocket Support** - Built-in WebSocket server with room management
-- **Server-Sent Events** - Real-time data streaming to clients
-- **Long Polling** - Fallback for real-time communication
+### 🛡️ Type Safety First
 
-#### **📊 Monitoring & Debugging:**
+```typescript
+// Full TypeScript integration with IntelliSense support
+import type { Context, Middleware, RouteHandler } from 'nextrush';
 
-- **Request Metrics** - Built-in performance monitoring
-- **Health Checks** - Automated endpoint health verification
-- **Error Tracking** - Comprehensive error logging and reporting
-- **Memory Monitoring** - Real-time memory usage tracking
+app.get('/users/:id', async (ctx: Context) => {
+  const userId: string = ctx.params.id; // Type-safe route parameters
+  const userData: User = ctx.body; // Type-safe request body
+  ctx.json({ user: userData }); // Type-safe response
+});
 
-### **🏗️ Architecture Highlights:**
+// Type-safe middleware composition
+const authMiddleware: Middleware = async (ctx, next) => {
+  ctx.state.user = await validateToken(ctx.headers.authorization);
+  await next();
+};
+```
 
-#### **Plugin System:**
+### 🎭 Choose Your API Style
 
 ```typescript
-// Load only what you need for maximum performance
-const app = createApp({
-  pluginMode: PluginMode.PERFORMANCE, // Only 4 essential plugins
-  // vs
-  pluginMode: PluginMode.FULL, // All 15+ plugins loaded
+// Convenience Methods (Recommended)
+app.get('/users', async ctx => {
+  ctx.json(await getUsers()); // Clean and concise
+});
+
+// Enhanced API (Express-inspired helpers)
+app.get('/users', async ctx => {
+  ctx.res.json(await getUsers()); // Familiar Express-like methods
+});
+
+// Configuration API (Fastify-style)
+app.get('/users', {
+  handler: async ctx => ctx.json(await getUsers()),
+  schema: { response: { 200: UserSchema } },
+  options: { tags: ['users'] },
 });
 ```
 
-#### **Memory Efficiency:**
+### 🌟 Core Features Comparison
+
+| Feature                       | NextRush v2     | Express         | Fastify         | Koa               |
+| ----------------------------- | --------------- | --------------- | --------------- | ----------------- |
+| **Security Middleware**       | Built-in        | Plugin required | Plugin required | Plugin required   |
+| **Validation & Sanitization** | Built-in        | Plugin required | Built-in        | Plugin required   |
+| **Template Engine**           | Built-in        | Plugin required | Plugin required | Plugin required   |
+| **WebSocket Support**         | Built-in        | Plugin required | Plugin required | Plugin required   |
+| **Event System (CQRS)**       | Dual system     | Plugin required | Plugin required | Plugin required   |
+| **Advanced Logging**          | Plugin included | Plugin required | Plugin required | Plugin required   |
+| **Error Classes**             | 8 custom types  | Basic           | Basic           | Basic             |
+| **Dependency Injection**      | Built-in        | Plugin required | Plugin required | Plugin required   |
+| **Smart Body Parser**         | Auto-detection  | Plugin required | Built-in        | Plugin required   |
+| **Static File Serving**       | Plugin included | Built-in        | Plugin required | Plugin required   |
+| **TypeScript Support**        | First-class     | Community       | First-class     | Community         |
+| **Dependencies**              | **0** ⭐        | 34+ packages    | 20+ packages    | 0 (needs plugins) |
+| **Performance (RPS)**         | ~13,261         | ~11,030         | ~22,717         | ~17,547           |
+
+---
+
+## ✨ Comprehensive Feature Set
+
+<table>
+<tr>
+<td width="50%">
+
+### Modern Development
+
+- **TypeScript First** - Full type safety with IntelliSense
+- **Zero Dependencies** - Pure Node.js, minimal footprint
+- **ESM & CJS** - Universal module compatibility
+- **Plugin System** - Extensible architecture
+- **Smart Body Parser** - Auto-detection & zero-copy operations
+- **Template Engine** - Built-in HTML rendering with auto-escaping
+
+</td>
+<td width="50%">
+
+### Production Ready
+
+- **Error Handling** - Custom error classes with context
+- **Advanced Logging** - Structured logs with multiple transports
+- **Security** - CORS, Helmet, Rate Limiting included
+- **Validation** - Schema validation & input sanitization
+- **Testing** - Test-friendly design, 1461 passing tests
+- **Static Files** - High-performance file serving
+- **Compression** - Gzip & Brotli support
+
+</td>
+</tr>
+<tr>
+<td width="50%">
+
+### Real-time & Events
+
+- **WebSocket Support** - RFC 6455 compliant implementation
+- **Room Management** - Built-in room system for grouping
+- **Broadcasting** - Efficient message delivery patterns
+- **Event System** - Simple events + CQRS/Event Sourcing
+- **Connection Pooling** - Scalable connection management
+- **Heartbeat** - Automatic connection health monitoring
+- **Pub/Sub** - Event-driven architecture support
+
+</td>
+<td width="50%">
+
+### Developer Experience
 
-- **Zero Dependencies** - No bloated node_modules
-- **Smart Caching** - Intelligent memory usage with TTL
-- **Buffer Pooling** - Optimized memory allocation for high-traffic
-- **Garbage Collection** - Minimal GC pressure design
+- **Enhanced Errors** - Contextual debugging information
+- **Request/Response Enhancers** - Express-inspired helpers
+- **Path Utilities** - URL & path manipulation tools
+- **Cookie Utilities** - Type-safe cookie management
+- **Dependency Injection** - Built-in DI container
+- **Dev Warnings** - Common mistake detection
+- **Performance Monitoring** - Built-in metrics collection
+
+</td>
+</tr>
+</table>
 
 ## 🚀 **Quick Start**
 
-### **Installation**
+### Prerequisites
+
+- **Node.js**: >= 20.0.0
+- **pnpm**: >= 10.0.0 (recommended) or npm/yarn/bun
+
+### Installation
 
 ```bash
-# NPM (recommended)
+# pnpm (recommended)
+pnpm add nextrush
+
+# npm
 npm install nextrush
 
-# Yarn
+# yarn
 yarn add nextrush
 
-# PNPM
-pnpm add nextrush
+# bun
+bun add nextrush
 ```
 
-### **Basic Usage**
+### Hello World
 
 ```typescript
-import { createApp, PluginMode } from 'nextrush';
+import { createApp } from 'nextrush';
 
-// Create app with full features (development)
 const app = createApp();
 
-// Or create app with performance mode (production)
-const productionApp = createApp({
-  pluginMode: PluginMode.PERFORMANCE, // 4 essential plugins only
-  enableEvents: false,
-  enableWebSocket: false,
+app.get('/', async ctx => {
+  ctx.json({
+    message: 'Hello NextRush v2! 🚀',
+    timestamp: new Date().toISOString(),
+  });
 });
 
-// Express.js-compatible routes work unchanged
-app.get('/api/users/:id', (req, res) => {
-  const { id } = req.params;
-  const { format } = req.query;
+app.listen(3000, () => {
+  console.log('🚀 Server running on http://localhost:3000');
+});
+```
 
-  res.json({
-    id,
-    name: 'John Doe',
-    format: format || 'default',
-  });
+### 30-Second API
+
+```typescript
+import { createApp } from 'nextrush';
+
+const app = createApp({
+  cors: true, // Enable CORS
+  debug: true, // Development mode
 });
 
-// POST with automatic body parsing
-app.post('/api/users', (req, res) => {
-  const userData = req.body; // Automatically parsed JSON
-  res.status(201).json({ created: userData });
+// Middleware
+app.use(async (ctx, next) => {
+  console.log(`📝 ${ctx.method} ${ctx.path}`);
+  await next();
 });
 
-app.listen(3000, () => {
-  console.log('🚀 NextRush server running on http://localhost:3000');
+// Routes with three different styles
+app.get('/simple', async ctx => {
+  ctx.json({ style: 'convenience' });
 });
+
+app.get('/express', async ctx => {
+  ctx.res.json({ style: 'express-like' });
+});
+
+app.post('/fastify', {
+  handler: async ctx => ctx.json({ style: 'fastify-style' }),
+  schema: {
+    body: {
+      type: 'object',
+      properties: { name: { type: 'string' } },
+    },
+  },
+});
+
+app.listen(3000);
 ```
 
-### **🔥 Advanced Features**
+---
+
+## 🎭 Multiple API Styles
 
-#### **File Uploads (Built-in)**
+NextRush v2 is **Koa-style at its core** with **three distinct API styles**—choose the approach that best fits your team's preferences:
+
+### Convenience Methods _(Recommended)_
 
 ```typescript
-// No multer needed - built-in file handling
-app.post('/upload', (req, res) => {
-  const file = req.file('document');
-  const metadata = req.body;
-
-  if (file) {
-    res.json({
-      uploaded: file.filename,
-      size: file.size,
-      metadata,
-    });
-  } else {
-    res.status(400).json({ error: 'No file uploaded' });
+app.get('/users/:id', async ctx => {
+  const user = await findUser(ctx.params.id);
+
+  if (!user) {
+    ctx.json({ error: 'User not found' }, 404);
+    return;
+  }
+
+  ctx.json(user); // Clean and concise
+});
+
+app.post('/users', async ctx => {
+  const user = await createUser(ctx.body);
+  ctx.json(user, 201); // Status code as second parameter
+});
+```
+
+### Enhanced API _(Express-inspired)_
+
+```typescript
+app.get('/users/:id', async ctx => {
+  const user = await findUser(ctx.params.id);
+
+  if (!user) {
+    ctx.res.status(404).json({ error: 'User not found' });
+    return;
   }
+
+  ctx.res.json(user); // Familiar Express-style methods
+});
+
+app.post('/users', async ctx => {
+  const user = await createUser(ctx.body);
+  ctx.res.status(201).json(user); // Chainable method calls
 });
 ```
 
-#### **WebSocket Support (Built-in)**
+### Configuration API _(Fastify-style)_
 
 ```typescript
-// No socket.io needed - built-in WebSocket
-app.ws('/chat', (ws, req) => {
-  console.log('New WebSocket connection');
+app.get('/users/:id', {
+  handler: async ctx => {
+    const user = await findUser(ctx.params.id);
+    ctx.json(user || { error: 'Not found' }, user ? 200 : 404);
+  },
+  schema: {
+    params: {
+      type: 'object',
+      properties: { id: { type: 'string', pattern: '^[0-9]+$' } },
+    },
+    response: {
+      200: { type: 'object', properties: { id: { type: 'string' } } },
+      404: { type: 'object', properties: { error: { type: 'string' } } },
+    },
+  },
+  options: {
+    name: 'getUser',
+    description: 'Retrieve user by ID',
+    tags: ['users'],
+  },
+});
+```
+
+---
+
+## 🌐 Real-time WebSocket Support
+
+Production-ready WebSocket server with zero dependencies and full TypeScript support:
+
+```typescript
+import { createApp, WebSocketPlugin, withWebSocket } from 'nextrush';
+import type { WSConnection } from 'nextrush';
+
+const app = createApp();
+
+// Install WebSocket plugin
+const wsPlugin = new WebSocketPlugin({
+  path: '/ws',
+  heartbeatMs: 30000,
+  maxConnections: 1000,
+  verifyClient: async req => {
+    // Optional: Custom authentication
+    const token = new URL(req.url || '', 'http://localhost').searchParams.get(
+      'token'
+    );
+    return !!token;
+  },
+});
+wsPlugin.install(app);
+
+// ✅ Get typed WebSocket application (Perfect IntelliSense!)
+const wsApp = withWebSocket(app);
+
+// Simple echo server with full type safety
+wsApp.ws('/echo', (socket: WSConnection) => {
+  socket.send('Welcome!');
 
-  ws.on('message', (data) => {
-    // Echo message to all connected clients
-    app.broadcast('chat', `User: ${data}`);
+  socket.onMessage((data: string | Buffer) => {
+    socket.send(`Echo: ${data}`);
+  });
+});
+
+// Room-based chat system
+wsApp.ws('/chat', (socket: WSConnection) => {
+  const room = 'general';
+
+  socket.join(room);
+  socket.send(`Joined room: ${room}`);
+
+  socket.onMessage((data: string | Buffer) => {
+    // Broadcast to all users in room using app-level method
+    wsApp.wsBroadcast(data.toString(), room);
   });
 
-  ws.on('close', () => {
-    console.log('WebSocket connection closed');
+  socket.onClose((code, reason) => {
+    console.log(`Client disconnected: ${code} - ${reason}`);
   });
 });
+
+app.listen(3000);
+```
+
+**Client Usage:**
+
+```javascript
+// Browser WebSocket client
+const ws = new WebSocket('ws://localhost:3000/chat');
+ws.onopen = () => {
+  console.log('Connected!');
+  ws.send('Hello everyone!');
+};
+ws.onmessage = event => console.log('Received:', event.data);
+ws.onerror = error => console.error('Error:', error);
+ws.onclose = () => console.log('Disconnected');
+
+// With authentication token
+const wsAuth = new WebSocket('ws://localhost:3000/echo?token=your-jwt-token');
 ```
 
-#### **Template Rendering (Built-in)**
+---
+
+## 🛡️ Built-in Security Middleware
 
 ```typescript
-// No view engine setup needed
-app.get('/profile/:username', (req, res) => {
-  const data = {
-    username: req.params.username,
-    posts: ['Hello World', 'Learning NextRush'],
-  };
+import { createApp } from 'nextrush';
+
+const app = createApp();
+
+// CORS - Cross-Origin Resource Sharing
+app.use(
+  app.cors({
+    origin: ['https://example.com'],
+    credentials: true,
+    methods: ['GET', 'POST', 'PUT', 'DELETE'],
+  })
+);
+
+// Helmet - Security headers
+app.use(
+  app.helmet({
+    contentSecurityPolicy: true,
+    xssFilter: true,
+    noSniff: true,
+    frameguard: { action: 'deny' },
+  })
+);
+
+// Rate Limiting - DDoS protection
+app.use(
+  app.rateLimiter({
+    windowMs: 15 * 60 * 1000, // 15 minutes
+    max: 100, // 100 requests per window
+    message: 'Too many requests',
+  })
+);
+
+// Request ID - Request tracing
+app.use(app.requestId());
+
+// Response Timer - Performance monitoring
+app.use(app.timer());
+```
+
+**Included Security Features:**
 
-  // Supports Mustache, Handlebars, EJS
-  res.render('profile.mustache', data);
+- **CORS** - Flexible origin control and credential handling
+- **Helmet** - 15+ security headers preconfigured
+- **Rate Limiting** - IP-based request throttling
+- **XSS Protection** - Automatic escaping in template engine
+- **Request Tracing** - Unique identifiers for request tracking
+- **Response Timing** - Performance measurement headers
+
+---
+
+## 📝 **Comprehensive Validation System**
+
+## 📏 Comprehensive Validation System
+
+```typescript
+import { validateRequest, sanitizeInput, ValidationError } from 'nextrush';
+
+// Define validation schema
+const userSchema = {
+  name: {
+    required: true,
+    type: 'string',
+    minLength: 2,
+    maxLength: 50,
+  },
+  email: {
+    required: true,
+    type: 'email',
+  },
+  age: {
+    type: 'number',
+    min: 18,
+    max: 120,
+  },
+  role: {
+    enum: ['user', 'admin', 'moderator'],
+  },
+};
+
+app.post('/users', async ctx => {
+  try {
+    // Validate request against schema
+    const userData = validateRequest(ctx, userSchema);
+
+    // Sanitize user input
+    const cleanData = sanitizeInput(userData);
+
+    const user = await createUser(cleanData);
+    ctx.json({ user }, 201);
+  } catch (error) {
+    if (error instanceof ValidationError) {
+      ctx.json(
+        {
+          error: 'Validation failed',
+          details: error.errors,
+        },
+        400
+      );
+    }
+  }
 });
 ```
 
-#### **Authentication & Security (Built-in)**
+**Validation Capabilities:**
+
+- **Type Checking** - string, number, boolean, email, URL, and more
+- **Length Validation** - minLength, maxLength constraints
+- **Range Validation** - min, max for numeric values
+- **Pattern Matching** - Regular expression validation
+- **Enum Validation** - Restricted value sets
+- **Custom Validation** - Extensible validation functions
+- **XSS Prevention** - Automatic input sanitization
+
+📚 **[Complete Validation Guide →](./docs/api/validation-utilities.md)**
+
+**Validation Features:**
+
+- **Type Checking** - string, number, boolean, email, URL, etc.
+- **Length Validation** - minLength, maxLength
+- **Range Validation** - min, max for numbers
+- **Pattern Matching** - Regex validation
+- **Enum Validation** - Allowed values
+- **Custom Validation** - Your own validation functions
+- **XSS Prevention** - Auto-sanitization
+
+📚 **[Complete Validation Guide →](./docs/api/validation-utilities.md)**
+
+---
+
+## 🎨 Template Engine
 
 ```typescript
-// Built-in JWT and session support
-app.post('/login', async (req, res) => {
-  const { username, password } = req.body;
-
-  if (await validateUser(username, password)) {
-    const token = req.signJWT({ username }, '24h');
-    res.json({ token, message: 'Login successful' });
-  } else {
-    res.status(401).json({ error: 'Invalid credentials' });
+import { createApp, TemplatePlugin } from 'nextrush';
+
+const app = createApp();
+
+// Setup template engine
+const templatePlugin = new TemplatePlugin({
+  viewsDir: './views',
+  cache: true,
+  helpers: {
+    formatDate: date => new Date(date).toLocaleDateString(),
+    currency: value => `$${Number(value).toFixed(2)}`,
+  },
+});
+
+templatePlugin.install(app);
+
+// Use templates
+app.get('/users/:id', async ctx => {
+  const user = await getUser(ctx.params.id);
+
+  await ctx.render('user-profile.html', {
+    title: 'User Profile',
+    user,
+    isAdmin: user.role === 'admin',
+  });
+});
+```
+
+**views/user-profile.html:**
+
+```html
+<!DOCTYPE html>
+<html>
+  <head>
+    <title>{{title}}</title>
+  </head>
+  <body>
+    <h1>{{user.name}}</h1>
+    <p>Email: {{user.email}}</p>
+    <p>Joined: {{user.createdAt | formatDate}}</p>
+
+    {{#if isAdmin}}
+    <button>Admin Panel</button>
+    {{/if}}
+
+    <!-- Loop through items -->
+    {{#each user.posts}}
+    <article>
+      <h2>{{this.title}}</h2>
+      <p>{{this.excerpt}}</p>
+    </article>
+    {{/each}}
+  </body>
+</html>
+```
+
+**Template Features:**
+
+- **Auto-escaping** - XSS protection by default
+- **Control Structures** - if/else, loops, with blocks
+- **Helpers** - Built-in & custom transformation functions
+- **Partials** - Reusable template components
+- **Layouts** - Consistent page structure
+- **Caching** - Fast production performance
+
+📚 **[Template Engine Documentation →](./docs/api/template-plugin.md)**
+
+---
+
+## 🚨 Advanced Error Handling
+
+```typescript
+import {
+  HttpError,
+  BadRequestError,
+  UnauthorizedError,
+  ForbiddenError,
+  NotFoundError,
+  ConflictError,
+  UnprocessableEntityError,
+  TooManyRequestsError,
+  InternalServerError,
+} from 'nextrush';
+
+// Custom error classes with proper status codes
+app.get('/users/:id', async ctx => {
+  const user = await db.user.findById(ctx.params.id);
+
+  if (!user) {
+    throw new NotFoundError('User not found', {
+      userId: ctx.params.id,
+      suggestion: 'Check the user ID',
+    });
+  }
+
+  if (ctx.state.user.id !== user.id) {
+    throw new ForbiddenError("Cannot access other user's data", {
+      requestedUserId: ctx.params.id,
+      currentUserId: ctx.state.user.id,
+    });
+  }
+
+  ctx.json({ user });
+});
+
+// Global error handler
+app.use(async (ctx, next) => {
+  try {
+    await next();
+  } catch (error) {
+    if (error instanceof HttpError) {
+      ctx.json(
+        {
+          error: error.message,
+          code: error.code,
+          details: error.details,
+        },
+        error.statusCode
+      );
+      return;
+    }
+
+    // Unexpected errors
+    ctx.json({ error: 'Internal server error' }, 500);
   }
 });
+```
+
+**Error Classes:**
+
+- **BadRequestError (400)** - Invalid request data
+- **UnauthorizedError (401)** - Authentication required
+- **ForbiddenError (403)** - Insufficient permissions
+- **NotFoundError (404)** - Resource not found
+- **ConflictError (409)** - Resource conflicts
+- **UnprocessableEntityError (422)** - Business rule violations
+- **TooManyRequestsError (429)** - Rate limit exceeded
+- **InternalServerError (500)** - Server errors
+
+📚 **[Complete Error Handling Guide →](./docs/api/errors.md)**
 
-// Protected route with built-in middleware
-app.get('/dashboard', req.requireAuth(), (req, res) => {
-  res.json({
-    message: `Welcome ${req.user.username}`,
-    dashboard: 'data',
+---
+
+## 🎪 Event-Driven Architecture
+
+NextRush v2 includes dual event systems: Simple Events (Express-style) + Advanced Event System (CQRS/Event Sourcing).
+
+### Simple Events API _(Express-style)_
+
+```typescript
+// Emit events
+await app.events.emit('user.registered', {
+  userId: user.id,
+  email: user.email,
+});
+
+// Listen to events
+app.events.on('user.registered', async data => {
+  await sendWelcomeEmail(data.email);
+  await createDefaultProfile(data.userId);
+  await trackAnalytics('User Registered', data);
+});
+
+// One-time handlers
+app.events.once('app.ready', async () => {
+  await warmupCache();
+  await initializeServices();
+});
+```
+
+### Advanced Event System _(CQRS/Event Sourcing)_
+
+```typescript
+// Define commands
+interface CreateUserCommand {
+  type: 'CreateUser';
+  data: { name: string; email: string };
+  metadata: { id: string; timestamp: Date; correlationId: string };
+}
+
+// Register command handlers
+app.eventSystem.registerCommandHandler(
+  'CreateUser',
+  async (command: CreateUserCommand) => {
+    const user = await db.user.create(command.data);
+
+    // Emit domain event
+    await app.eventSystem.emit({
+      type: 'user.created',
+      data: { userId: user.id, email: user.email },
+      timestamp: new Date(),
+      metadata: {
+        aggregateId: user.id,
+        version: 1,
+      },
+    });
+
+    return user;
+  }
+);
+
+// Subscribe to domain events
+app.eventSystem.subscribe('user.created', async event => {
+  await analytics.track('User Created', {
+    userId: event.data.userId,
+    correlationId: event.metadata.correlationId,
   });
 });
+
+// Execute commands with CQRS
+app.post('/users', async ctx => {
+  const command: CreateUserCommand = {
+    type: 'CreateUser',
+    data: ctx.body,
+    metadata: {
+      id: crypto.randomUUID(),
+      timestamp: new Date(),
+      correlationId: ctx.id,
+    },
+  };
+
+  const user = await app.eventSystem.dispatch(command);
+  ctx.json({ user }, 201);
+});
 ```
 
-### **🔄 Migrating from Express.js**
+**Event System Features:**
 
-Most Express.js code works **unchanged** with NextRush:
+- **Simple Events** - Express-style emit/on/once patterns
+- **CQRS** - Command Query Responsibility Segregation
+- **Event Sourcing** - Domain event tracking and replay
+- **Saga Patterns** - Complex workflow orchestration
+- **Pub/Sub** - Event broadcasting capabilities
+- **Correlation IDs** - Request tracing across services
+- **Event Store** - Event history and replay functionality
 
-```diff
-- const express = require('express');
-- const bodyParser = require('body-parser');
-- const cors = require('cors');
-- const helmet = require('helmet');
-- const multer = require('multer');
+📚 **[Complete Event System Guide →](./docs/api/events.md)**
 
-+ import { createApp } from 'nextrush';
+---
+
+## 📊 Advanced Logging Plugin
+
+```typescript
+import { LoggerPlugin } from 'nextrush';
+
+// Configure advanced logging
+const loggerPlugin = new LoggerPlugin({
+  level: 'info',
+  format: 'json',
+  transports: [
+    {
+      type: 'console',
+      colorize: true,
+    },
+    {
+      type: 'file',
+      filename: 'logs/app.log',
+      maxSize: 10485760, // 10MB
+      maxFiles: 5,
+    },
+    {
+      type: 'file',
+      filename: 'logs/errors.log',
+      level: 'error',
+      maxSize: 10485760,
+    },
+  ],
+  includeTimestamp: true,
+  includeMetadata: true,
+});
 
-- const app = express();
-- app.use(bodyParser.json());
-- app.use(cors());
-- app.use(helmet());
-- const upload = multer({ dest: 'uploads/' });
+loggerPlugin.install(app);
 
-+ const app = createApp(); // All middleware built-in!
+// Use in routes
+app.get('/api/data', async ctx => {
+  ctx.logger.info('Fetching data', {
+    userId: ctx.state.user?.id,
+    endpoint: '/api/data',
+  });
 
-// All your existing routes work exactly the same
-app.get('/api/users', (req, res) => {
-  res.json({ users: [] });
+  try {
+    const data = await fetchData();
+    ctx.logger.debug('Data fetched successfully', { count: data.length });
+    ctx.json({ data });
+  } catch (error) {
+    ctx.logger.error('Failed to fetch data', {
+      error: error.message,
+      stack: error.stack,
+    });
+    throw error;
+  }
 });
+```
+
+**Logger Features:**
+
+- **Multiple Transports** - Console, file, and custom transports
+- **Log Levels** - debug, info, warn, error, fatal
+- **Structured Logging** - JSON format with metadata
+- **File Rotation** - Size-based and time-based rotation
+- **Colorized Output** - Enhanced development experience
+- **Performance Metrics** - Request timing and throughput tracking
+- **Custom Formatters** - Extensible log formatting
+
+📚 **[Logger Plugin Documentation →](./docs/api/logger-plugin.md)**
+
+---
+
+## 🏗️ **Advanced Features**
+
+### Modular Router System
+
+```typescript
+import { createApp, createRouter } from 'nextrush';
+
+const app = createApp();
+
+// Create sub-routers
+const userRouter = createRouter();
+const adminRouter = createRouter();
+
+// User routes
+userRouter.get('/profile', async ctx => ctx.json({ user: 'profile' }));
+userRouter.post('/login', async ctx => ctx.json({ message: 'Logged in' }));
+
+// Admin routes
+adminRouter.get('/dashboard', async ctx => ctx.json({ admin: 'dashboard' }));
+adminRouter.get('/users', async ctx => ctx.json({ admin: 'users list' }));
+
+// Mount routers
+app.use('/users', userRouter);
+app.use('/admin', adminRouter);
+```
+
+### Custom Middleware Development
+
+```typescript
+import type { Middleware, Context } from 'nextrush';
+
+// Simple middleware
+const logger: Middleware = async (ctx, next) => {
+  const start = Date.now();
+  console.log(`🔄 ${ctx.method} ${ctx.path}`);
+
+  await next();
+
+  const duration = Date.now() - start;
+  console.log(`✅ ${ctx.status} ${duration}ms`);
+};
+
+// Authentication middleware with proper error handling
+const requireAuth: Middleware = async (ctx, next) => {
+  const token = ctx.headers.authorization?.replace('Bearer ', '');
+
+  if (!token) {
+    throw new UnauthorizedError('Authentication token required', {
+      hint: 'Include Authorization: Bearer <token> header',
+    });
+  }
+
+  try {
+    ctx.state.user = await validateToken(token);
+    await next();
+  } catch (error) {
+    throw new UnauthorizedError('Invalid authentication token', {
+      reason: error.message,
+    });
+  }
+};
+
+// Role-based authorization
+const requireRole = (role: string): Middleware => {
+  return async (ctx, next) => {
+    if (!ctx.state.user) {
+      throw new UnauthorizedError('Authentication required');
+    }
+
+    if (!ctx.state.user.roles.includes(role)) {
+      throw new ForbiddenError(`${role} role required`, {
+        userRoles: ctx.state.user.roles,
+        requiredRole: role,
+      });
+    }
+
+    await next();
+  };
+};
+
+// Rate limiting middleware
+const rateLimiter: Middleware = async (ctx, next) => {
+  const key = ctx.ip;
+  const limit = 100;
+  const windowMs = 15 * 60 * 1000;
+
+  const requests = await getRequestCount(key, windowMs);
 
-- app.post('/upload', upload.single('file'), (req, res) => {
-+ app.post('/upload', (req, res) => {
--   res.json({ file: req.file });
-+   res.json({ file: req.file('file') }); // Built-in file handling
+  if (requests >= limit) {
+    throw new TooManyRequestsError('Rate limit exceeded', {
+      limit,
+      retryAfter: Math.ceil(windowMs / 1000),
+    });
+  }
+
+  await incrementRequestCount(key, windowMs);
+  await next();
+};
+
+// Use middleware
+app.use(logger);
+app.use('/api', requireAuth);
+app.use('/admin', requireRole('admin'));
+```
+
+📚 **[Middleware Development Guide →](./docs/guides/middleware-development.md)**
+
+### Enhanced Response Methods
+
+```typescript
+// JSON response with status code
+app.get('/api/users', async ctx => {
+  const users = await getUsers();
+  ctx.json({ users }, 200);
 });
+
+// HTML response
+app.get('/page', async ctx => {
+  ctx.html('<h1>Welcome to NextRush</h1>');
+});
+
+// File download with options
+app.get('/download', async ctx => {
+  ctx.file('./document.pdf', {
+    filename: 'report.pdf',
+    contentType: 'application/pdf',
+  });
+});
+
+// Redirect with status code
+app.get('/old-url', async ctx => {
+  ctx.redirect('/new-url', 301); // Permanent redirect
+});
+
+// CSV export
+app.get('/export/users', async ctx => {
+  const users = await getUsers();
+  const csv = users.map(u => `${u.name},${u.email}`).join('\n');
+  ctx.csv(`name,email\n${csv}`, 'users.csv');
+});
+
+// Stream response
+app.get('/stream', async ctx => {
+  const stream = fs.createReadStream('./large-file.txt');
+  ctx.stream(stream, 'text/plain');
+});
+
+// Set custom headers
+app.get('/api/data', async ctx => {
+  ctx.set('X-Custom-Header', 'value');
+  ctx.set('Cache-Control', 'max-age=3600');
+  ctx.json({ data: [] });
+});
+
+// Cookie management
+app.get('/set-cookie', async ctx => {
+  ctx.setCookie('session', 'abc123', {
+    httpOnly: true,
+    secure: true,
+    maxAge: 3600000,
+    sameSite: 'strict',
+  });
+  ctx.json({ message: 'Cookie set' });
+});
+
+app.get('/get-cookie', async ctx => {
+  const session = ctx.getCookie('session');
+  ctx.json({ session });
+});
+```
+
+📚 **[Enhanced Request/Response API →](./docs/api/enhancers.md)**
+
+## 📖 Complete API Reference
+
+### Context Object
+
+```typescript
+// ===================== Request Properties =====================
+ctx.req        // Native HTTP request object
+ctx.res        // Enhanced response object
+ctx.body       // Parsed request body (JSON, form, etc.)
+ctx.method     // HTTP method (GET, POST, PUT, DELETE, etc.)
+ctx.path       // Request path (/users/123)
+ctx.url        // Full request URL
+ctx.query      // Query parameters (?page=1 → { page: '1' })
+ctx.headers    // Request headers (lowercase keys)
+ctx.params     // Route parameters (/users/:id → { id: '123' })
+ctx.cookies    // Parsed cookies
+ctx.ip         // Client IP address
+ctx.secure     // Is HTTPS?
+ctx.protocol   // Request protocol (http/https)
+ctx.hostname   // Request hostname
+ctx.origin     // Request origin (protocol + host)
+ctx.state      // Custom request-scoped state
+
+// ===================== Response Methods =====================
+// Convenience API (Recommended)
+ctx.json(data, status?)           // Send JSON response
+ctx.html(html, status?)            // Send HTML response
+ctx.text(text, status?)            // Send plain text
+ctx.csv(data, filename?)           // Send CSV file
+ctx.file(path, options?)           // Send file download
+ctx.stream(stream, contentType?)   // Send stream response
+ctx.redirect(url, status?)         // Redirect to URL
+
+// Express-like API (Enhanced)
+ctx.res.json(data, status?)        // Send JSON
+ctx.res.status(code)               // Set status code (chainable)
+ctx.res.send(data)                 // Auto-detect content type
+ctx.res.sendFile(path)             // Send file
+ctx.res.render(template, data)     // Render template
+
+// ===================== Header & Cookie Methods =====================
+ctx.get(headerName)                // Get request header
+ctx.set(headerName, value)         // Set response header
+ctx.setCookie(name, value, opts)   // Set cookie
+ctx.getCookie(name)                // Get cookie value
+ctx.clearCookie(name)              // Delete cookie
+
+// ===================== Utility Properties =====================
+ctx.id                             // Unique request ID
+ctx.logger                         // Request-scoped logger
+ctx.services                       // DI container services
+ctx.app                            // Application instance
 ```
 
-### **⚡ Performance Optimization**
+### Application Methods
 
 ```typescript
-// For maximum performance (production)
-const app = createApp({
-  pluginMode: PluginMode.PERFORMANCE,
-  enableEvents: false,
-  enableWebSocket: false,
-  enableMetrics: false,
-  maxRequestSize: 1024 * 1024, // 1MB limit
-  timeout: 30000, // 30 second timeout
+// ===================== HTTP Methods =====================
+app.get(path, ...handlers)         // GET route
+app.post(path, ...handlers)        // POST route
+app.put(path, ...handlers)         // PUT route
+app.delete(path, ...handlers)      // DELETE route
+app.patch(path, ...handlers)       // PATCH route
+app.head(path, ...handlers)        // HEAD route
+app.options(path, ...handlers)     // OPTIONS route
+app.all(path, ...handlers)         // All HTTP methods
+
+// ===================== Middleware =====================
+app.use(...middleware)             // Global middleware
+app.use(path, ...middleware)       // Path-specific middleware
+
+// ===================== Built-in Middleware =====================
+app.cors(options)                  // CORS middleware
+app.helmet(options)                // Security headers
+app.rateLimiter(options)           // Rate limiting
+app.compression(options)           // Gzip/Brotli compression
+app.requestId(options)             // Request ID tracking
+app.timer()                        // Response time header
+app.smartBodyParser(options)       // Auto body parsing
+
+// ===================== Event System =====================
+app.events.emit(event, data)       // Emit simple event
+app.events.on(event, handler)      // Listen to event
+app.events.once(event, handler)    // One-time listener
+app.events.off(event, handler?)    // Remove listener
+
+app.eventSystem.dispatch(op)       // CQRS dispatch
+app.eventSystem.executeCommand(c)  // Execute command
+app.eventSystem.executeQuery(q)    // Execute query
+app.eventSystem.subscribe(e, h)    // Subscribe to domain event
+
+// ===================== Server Control =====================
+app.listen(port, callback?)        // Start HTTP server
+app.close(callback?)               // Stop server gracefully
+```
+
+### Router Methods
+
+```typescript
+// Create router
+const router = createRouter('/prefix');
+
+// HTTP methods
+router.get(path, handler);
+router.post(path, handler);
+router.put(path, handler);
+router.delete(path, handler);
+router.patch(path, handler);
+
+// Middleware
+router.use(middleware);
+
+// Mount router
+app.use('/api', router);
+```
+
+---
+
+## 🧪 Testing
+
+```typescript
+import { createApp } from 'nextrush';
+
+describe('NextRush Application', () => {
+  it('should handle GET requests', async () => {
+    const app = createApp();
+
+    app.get('/test', async ctx => {
+      ctx.json({ message: 'OK' });
+    });
+
+    // Your test implementation
+  });
 });
+```
+
+---
+
+## 🔥 Enhanced Body Parser
+
+Enterprise-grade body parsing with zero-copy operations:
 
-// Results in ~20% better performance
-// NextRush: 5,784 RPS → ~7,000 RPS (estimated)
+```typescript
+// Auto-parsing (recommended)
+app.use(app.smartBodyParser());
+
+// Advanced configuration
+app.use(
+  app.smartBodyParser({
+    maxSize: 10 * 1024 * 1024, // 10MB
+    enableStreaming: true,
+    autoDetectContentType: true,
+    enableMetrics: true,
+  })
+);
+
+// Supports JSON, form-data, text, multipart
+app.post('/api/data', ctx => {
+  const data = ctx.body; // Already parsed!
+  ctx.json({ received: data });
+});
 ```
 
-## 📚 **Learning Documentation**
+**Features:** Zero-copy buffers • Auto-detection • Streaming • Memory-pooled • Cross-platform
+
+📚 **[Full Documentation →](./docs/api/built-in-middleware.md)**
+
+## 📚 Documentation
+
+Comprehensive guides, API references, and architecture deep-dives:
+
+### Getting Started
 
-- **[📖 Lessons Learned](./LESSONS-LEARNED.md)** - My complete learning journey
-- **[📋 Project Status](./PROJECT-STATUS.md)** - Final achievements and metrics
-- **[🚪 Exit Plan](./EXIT-PLAN.md)** - How to properly conclude a learning project
-- **[📊 Benchmarks](./professional-benchmarks/)** - Complete performance testing suite
+- **[Getting Started Guide](./docs/guides/getting-started.md)** - Your first NextRush v2 app in 5 minutes
+- **[Migration from Express](./docs/guides/migration-guide.md)** - Migrate from Express.js
+- **[Migration from Fastify](./docs/guides/migration-guide.md)** - Migrate from Fastify
 
-## 🎓 **Educational Value**
+### Essential Guides
 
-### **What I Learned:**
+- **[Routing Guide](./docs/api/routing.md)** - All three routing styles explained (Convenience, Enhanced, Fastify-style)
+- **[Middleware Development](./docs/guides/middleware-development.md)** - Create custom middleware
+- **[Plugin Development](./docs/guides/plugin-development.md)** - Build powerful plugins
+- **[Error Handling Guide](./docs/guides/error-handling.md)** - Robust error management patterns
+- **[Testing Guide](./docs/guides/testing-guide.md)** - Unit, integration, and E2E testing
+- **[Production Deployment](./docs/guides/production-deployment.md)** - Deploy to production
 
-- Framework architecture and design patterns
-- Plugin systems and extensible architectures
-- TypeScript advanced patterns and techniques
-- Performance testing and optimization
-- NPM package development and publishing
+### Core API Reference
 
-### **Key Insights:**
+- **[Application API](./docs/api/application.md)** - Core application methods and lifecycle
+- **[Context API](./docs/api/context.md)** - Request/response context (Koa-style)
+- **[Routing API](./docs/api/routing.md)** - Router and route handlers
+- **[Middleware API](./docs/api/middleware.md)** - Middleware system and patterns
+- **[Built-in Middleware](./docs/api/built-in-middleware.md)** - CORS, Helmet, Rate Limiting, Body Parser
+- **[Events API](./docs/api/events.md)** - Simple Events + Advanced Event System (CQRS)
+- **[Enhanced Request/Response](./docs/api/enhancers.md)** - Express-like helper methods
 
-- **Architecture planning** is more important than coding speed
-- **Simple solutions** often outperform complex optimizations
-- **Plugin systems** must be designed from day 1
-- **Testing** should come before features, not after
+### Advanced Features
 
-## 🚀 **Next Steps**
+- **[Error Handling API](./docs/api/errors.md)** - Custom error classes and error middleware
+- **[Validation Utilities](./docs/api/validation-utilities.md)** - Schema validation and data sanitization
+- **[Configuration & Validation](./docs/api/configuration.md)** - Application configuration
+- **[Path Utilities](./docs/api/path-utilities.md)** - URL and path manipulation helpers
+- **[Developer Experience](./docs/api/developer-experience.md)** - Enhanced error messages and debugging
 
-This project achieved its educational goals. The knowledge gained will be applied to **NextRush v2.0** - a complete rewrite with:
+### Plugin APIs
 
-- ✅ Architecture-first approach
-- ✅ Test-driven development
-- ✅ Incremental feature addition
-- ✅ Performance optimization from day 1
+- **[Logger Plugin](./docs/api/logger-plugin.md)** - Advanced structured logging with transports
+- **[WebSocket Plugin](./docs/api/websocket-plugin.md)** - Real-time WebSocket communication
+- **[Static Files Plugin](./docs/api/static-files-plugin.md)** - High-performance static file serving
+- **[Template Plugin](./docs/api/template-plugin.md)** - HTML template rendering engine
 
-## 📄 **License**
+### Architecture Deep-Dives
 
-MIT License - see [LICENSE](./LICENSE) file for details.
+- **[Plugin System](./docs/architecture/plugin-system.md)** - Plugin architecture and lifecycle
+- **[Dependency Injection](./docs/architecture/dependency-injection.md)** - DI container and service resolution
+- **[Orchestration System](./docs/architecture/orchestration-system.md)** - Application orchestration patterns
+- **[Optimized Router](./docs/architecture/optimized-router-deep-dive.md)** - Router internals and performance
+
+### Performance & Benchmarks
+
+- **Benchmarks** - Performance comparisons with Express, Koa, and Fastify
+- **Performance Guide** - Optimization techniques and best practices
+- **Memory Management** - Efficient memory usage patterns
+
+## 🤝 Contributing
+
+Contributions are welcome! Please see our [Contributing Guide](CONTRIBUTING.md) for details on how to get started.
+
+## 📄 License
+
+This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
+
+## 🙏 Acknowledgments
+
+- **Express.js** - Intuitive API design patterns
+- **Koa** - Powerful async middleware architecture
+- **Fastify** - Object-based route configuration approach
+- **TypeScript** - Type safety and enhanced developer experience
 
 ---
 
 <div align="center">
 
-**🎓 Successfully completed learning project!**
-
-_Built with ❤️ for education and shared for learning_
+**Built with precision by [Tanzim Hossain](https://github.com/0xTanzim)**
 
-[⭐ Star on GitHub](https://github.com/0xTanzim/nextRush) • [📖 Learn More](./LESSONS-LEARNED.md) • [🚀 NextRush v2.0 Coming Soon]
+[Report Bug](https://github.com/0xTanzim/nextrush/issues) • [Request Feature](https://github.com/0xTanzim/nextrush/issues) • [Discussions](https://github.com/0xTanzim/nextrush/discussions)
 
 </div>