omgkit 2.2.0 → 2.3.0

package/plugin/skills/frameworks/express/SKILL.md

@@ -1,1381 +1,175 @@
 ---
-name: express
-description: Enterprise Express.js development with TypeScript, middleware patterns, and production-ready APIs
-category: frameworks
-triggers:
-  - express
-  - expressjs
-  - express.js
-  - node api
-  - node rest api
-  - express middleware
-  - express routing
-  - node backend
+name: building-express-apis
+description: Builds production Express.js APIs with TypeScript, middleware patterns, authentication, and error handling. Use when creating Node.js backends, REST APIs, or Express applications.
 ---
 
 # Express.js
 
-Enterprise-grade **Express.js development** following industry best practices. This skill covers TypeScript integration, middleware patterns, authentication, error handling, validation, testing, and production deployment configurations used by top engineering teams.
-
-## Purpose
-
-Build scalable Node.js APIs with confidence:
-
-- Design clean API architectures with proper routing
-- Implement robust middleware patterns
-- Handle authentication and authorization securely
-- Validate requests with comprehensive schemas
-- Write comprehensive tests for reliability
-- Deploy production-ready applications
-- Optimize performance for high traffic
-
-## Features
-
-### 1. TypeScript Project Setup
+## Quick Start
 
 ```typescript
-// src/app.ts
-import express, { Application, Request, Response, NextFunction } from 'express';
+import express from 'express';
 import cors from 'cors';
 import helmet from 'helmet';
-import compression from 'compression';
-import rateLimit from 'express-rate-limit';
-import { pinoHttp } from 'pino-http';
-import { errorHandler } from './middleware/errorHandler';
-import { notFoundHandler } from './middleware/notFoundHandler';
-import { apiRouter } from './routes';
-import { config } from './config';
-import { logger } from './utils/logger';
-
-export function createApp(): Application {
-  const app = express();
-
-  // Security middleware
-  app.use(helmet());
-  app.use(cors({
-    origin: config.cors.origins,
-    credentials: true,
-    methods: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'],
-    allowedHeaders: ['Content-Type', 'Authorization'],
-  }));
-
-  // Rate limiting
-  app.use(rateLimit({
-    windowMs: 15 * 60 * 1000, // 15 minutes
-    max: 100,
-    standardHeaders: true,
-    legacyHeaders: false,
-    message: { error: 'Too many requests, please try again later.' },
-  }));
-
-  // Request parsing
-  app.use(express.json({ limit: '10mb' }));
-  app.use(express.urlencoded({ extended: true, limit: '10mb' }));
-  app.use(compression());
-
-  // Logging
-  app.use(pinoHttp({
-    logger,
-    customLogLevel: (req, res, err) => {
-      if (res.statusCode >= 500 || err) return 'error';
-      if (res.statusCode >= 400) return 'warn';
-      return 'info';
-    },
-  }));
 
-  // Health check
-  app.get('/health', (req, res) => {
-    res.json({ status: 'healthy', timestamp: new Date().toISOString() });
-  });
+const app = express();
 
-  // API routes
-  app.use('/api/v1', apiRouter);
+app.use(helmet());
+app.use(cors());
+app.use(express.json());
 
-  // Error handling
-  app.use(notFoundHandler);
-  app.use(errorHandler);
-
-  return app;
-}
-
-// src/server.ts
-import { createApp } from './app';
-import { config } from './config';
-import { logger } from './utils/logger';
-import { connectDatabase } from './database';
+app.get('/api/health', (req, res) => {
+  res.json({ status: 'ok' });
+});
 
-async function bootstrap() {
-  try {
-    await connectDatabase();
-    logger.info('Database connected');
+app.listen(3000);
+```
 
-    const app = createApp();
-    const server = app.listen(config.port, () => {
-      logger.info(`Server running on port ${config.port}`);
-    });
+## Features
 
-    // Graceful shutdown
-    const shutdown = async (signal: string) => {
-      logger.info(`${signal} received, shutting down gracefully`);
-      server.close(async () => {
-        logger.info('HTTP server closed');
-        process.exit(0);
-      });
+| Feature | Description | Guide |
+|---------|-------------|-------|
+| Project Setup | TypeScript config, middleware stack | [SETUP.md](SETUP.md) |
+| Routing | Controllers, validation, async handlers | [ROUTING.md](ROUTING.md) |
+| Middleware | Auth, validation, error handling | [MIDDLEWARE.md](MIDDLEWARE.md) |
+| Database | Prisma/TypeORM integration | [DATABASE.md](DATABASE.md) |
+| Testing | Jest, supertest patterns | [TESTING.md](TESTING.md) |
+| Deployment | Docker, PM2, production config | [DEPLOYMENT.md](DEPLOYMENT.md) |
 
-      setTimeout(() => {
-        logger.error('Forced shutdown after timeout');
-        process.exit(1);
-      }, 10000);
-    };
+## Common Patterns
 
-    process.on('SIGTERM', () => shutdown('SIGTERM'));
-    process.on('SIGINT', () => shutdown('SIGINT'));
-  } catch (error) {
-    logger.error('Failed to start server', error);
-    process.exit(1);
-  }
-}
-
-bootstrap();
-```
-
-### 2. Middleware Patterns
+### Controller Pattern
 
 ```typescript
-// src/middleware/auth.ts
+// controllers/users.ts
 import { Request, Response, NextFunction } from 'express';
-import jwt from 'jsonwebtoken';
-import { config } from '../config';
-import { AppError } from '../errors/AppError';
 import { UserService } from '../services/UserService';
 
-export interface AuthRequest extends Request {
-  user?: {
-    id: string;
-    email: string;
-    role: string;
-  };
-}
-
-export function authenticate() {
-  return async (req: AuthRequest, res: Response, next: NextFunction) => {
-    try {
-      const authHeader = req.headers.authorization;
-      if (!authHeader?.startsWith('Bearer ')) {
-        throw new AppError('No token provided', 401, 'UNAUTHORIZED');
-      }
-
-      const token = authHeader.substring(7);
-      const decoded = jwt.verify(token, config.jwt.secret) as {
-        userId: string;
-        email: string;
-        role: string;
-      };
-
-      // Optionally verify user still exists
-      const user = await UserService.findById(decoded.userId);
-      if (!user) {
-        throw new AppError('User not found', 401, 'UNAUTHORIZED');
-      }
-
-      req.user = {
-        id: decoded.userId,
-        email: decoded.email,
-        role: decoded.role,
-      };
-
-      next();
-    } catch (error) {
-      if (error instanceof jwt.JsonWebTokenError) {
-        next(new AppError('Invalid token', 401, 'INVALID_TOKEN'));
-      } else if (error instanceof jwt.TokenExpiredError) {
-        next(new AppError('Token expired', 401, 'TOKEN_EXPIRED'));
-      } else {
-        next(error);
-      }
-    }
-  };
-}
-
-export function authorize(...roles: string[]) {
-  return (req: AuthRequest, res: Response, next: NextFunction) => {
-    if (!req.user) {
-      return next(new AppError('Authentication required', 401, 'UNAUTHORIZED'));
-    }
-
-    if (!roles.includes(req.user.role)) {
-      return next(new AppError('Insufficient permissions', 403, 'FORBIDDEN'));
-    }
-
-    next();
-  };
-}
-
-// src/middleware/validate.ts
-import { Request, Response, NextFunction } from 'express';
-import { ZodSchema, ZodError } from 'zod';
-import { AppError } from '../errors/AppError';
-
-interface ValidationSchemas {
-  body?: ZodSchema;
-  query?: ZodSchema;
-  params?: ZodSchema;
-}
+export class UserController {
+  constructor(private userService: UserService) {}
 
-export function validate(schemas: ValidationSchemas) {
-  return async (req: Request, res: Response, next: NextFunction) => {
+  getAll = async (req: Request, res: Response, next: NextFunction) => {
     try {
-      if (schemas.body) {
-        req.body = await schemas.body.parseAsync(req.body);
-      }
-      if (schemas.query) {
-        req.query = await schemas.query.parseAsync(req.query);
-      }
-      if (schemas.params) {
-        req.params = await schemas.params.parseAsync(req.params);
-      }
-      next();
+      const users = await this.userService.findAll();
+      res.json(users);
     } catch (error) {
-      if (error instanceof ZodError) {
-        const details = error.errors.map(err => ({
-          path: err.path.join('.'),
-          message: err.message,
-        }));
-        next(new AppError('Validation failed', 400, 'VALIDATION_ERROR', details));
-      } else {
-        next(error);
-      }
+      next(error);
     }
   };
-}
-
-// src/middleware/requestId.ts
-import { Request, Response, NextFunction } from 'express';
-import { v4 as uuidv4 } from 'uuid';
-
-export interface RequestWithId extends Request {
-  id: string;
-}
-
-export function requestId() {
-  return (req: RequestWithId, res: Response, next: NextFunction) => {
-    req.id = (req.headers['x-request-id'] as string) || uuidv4();
-    res.setHeader('X-Request-ID', req.id);
-    next();
-  };
-}
-
-// src/middleware/cache.ts
-import { Request, Response, NextFunction } from 'express';
-import { redis } from '../database/redis';
-
-interface CacheOptions {
-  ttl?: number;
-  keyGenerator?: (req: Request) => string;
-}
-
-export function cache(options: CacheOptions = {}) {
-  const { ttl = 300, keyGenerator } = options;
-
-  return async (req: Request, res: Response, next: NextFunction) => {
-    if (req.method !== 'GET') {
-      return next();
-    }
-
-    const key = keyGenerator?.(req) || `cache:${req.originalUrl}`;
 
+  getById = async (req: Request, res: Response, next: NextFunction) => {
     try {
-      const cached = await redis.get(key);
-      if (cached) {
-        res.setHeader('X-Cache', 'HIT');
-        return res.json(JSON.parse(cached));
-      }
-
-      // Override res.json to cache the response
-      const originalJson = res.json.bind(res);
-      res.json = (body: unknown) => {
-        redis.setex(key, ttl, JSON.stringify(body));
-        res.setHeader('X-Cache', 'MISS');
-        return originalJson(body);
-      };
-
-      next();
+      const user = await this.userService.findById(req.params.id);
+      if (!user) return res.status(404).json({ error: 'Not found' });
+      res.json(user);
     } catch (error) {
-      // If cache fails, continue without caching
-      next();
+      next(error);
     }
   };
 }
 ```
 
-### 3. Error Handling
+### Error Handler
 
 ```typescript
-// src/errors/AppError.ts
-export class AppError extends Error {
-  public readonly statusCode: number;
-  public readonly code: string;
-  public readonly isOperational: boolean;
-  public readonly details?: unknown;
+// middleware/errorHandler.ts
+import { Request, Response, NextFunction } from 'express';
 
+export class AppError extends Error {
   constructor(
+    public statusCode: number,
     message: string,
-    statusCode: number = 500,
-    code: string = 'INTERNAL_ERROR',
-    details?: unknown,
-    isOperational: boolean = true
+    public isOperational = true
   ) {
     super(message);
-    this.statusCode = statusCode;
-    this.code = code;
-    this.isOperational = isOperational;
-    this.details = details;
-
-    Error.captureStackTrace(this, this.constructor);
-  }
-}
-
-export class NotFoundError extends AppError {
-  constructor(resource: string, id?: string) {
-    super(
-      id ? `${resource} with id ${id} not found` : `${resource} not found`,
-      404,
-      'NOT_FOUND'
-    );
   }
 }
 
-export class ValidationError extends AppError {
-  constructor(message: string, details?: unknown) {
-    super(message, 400, 'VALIDATION_ERROR', details);
-  }
-}
-
-export class UnauthorizedError extends AppError {
-  constructor(message: string = 'Unauthorized') {
-    super(message, 401, 'UNAUTHORIZED');
-  }
-}
-
-export class ForbiddenError extends AppError {
-  constructor(message: string = 'Forbidden') {
-    super(message, 403, 'FORBIDDEN');
-  }
-}
-
-export class ConflictError extends AppError {
-  constructor(message: string) {
-    super(message, 409, 'CONFLICT');
-  }
-}
-
-// src/middleware/errorHandler.ts
-import { Request, Response, NextFunction } from 'express';
-import { AppError } from '../errors/AppError';
-import { logger } from '../utils/logger';
-import { config } from '../config';
-
 export function errorHandler(
   err: Error,
   req: Request,
   res: Response,
   next: NextFunction
 ) {
-  // Log error
-  logger.error({
-    error: err.message,
-    stack: err.stack,
-    path: req.path,
-    method: req.method,
-    body: req.body,
-  });
-
-  // Handle known operational errors
   if (err instanceof AppError) {
-    return res.status(err.statusCode).json({
-      error: {
-        code: err.code,
-        message: err.message,
-        details: err.details,
-      },
-    });
-  }
-
-  // Handle Prisma errors
-  if (err.constructor.name === 'PrismaClientKnownRequestError') {
-    const prismaError = err as { code: string; meta?: { target?: string[] } };
-    if (prismaError.code === 'P2002') {
-      const field = prismaError.meta?.target?.[0] || 'field';
-      return res.status(409).json({
-        error: {
-          code: 'CONFLICT',
-          message: `A record with this ${field} already exists`,
-        },
-      });
-    }
-    if (prismaError.code === 'P2025') {
-      return res.status(404).json({
-        error: {
-          code: 'NOT_FOUND',
-          message: 'Record not found',
-        },
-      });
-    }
+    return res.status(err.statusCode).json({ error: err.message });
   }
 
-  // Handle unknown errors
-  const message = config.isProduction
-    ? 'An unexpected error occurred'
-    : err.message;
-
-  res.status(500).json({
-    error: {
-      code: 'INTERNAL_ERROR',
-      message,
-      ...(config.isDevelopment && { stack: err.stack }),
-    },
-  });
-}
-
-// src/middleware/notFoundHandler.ts
-import { Request, Response } from 'express';
-
-export function notFoundHandler(req: Request, res: Response) {
-  res.status(404).json({
-    error: {
-      code: 'NOT_FOUND',
-      message: `Route ${req.method} ${req.path} not found`,
-    },
-  });
+  console.error(err);
+  res.status(500).json({ error: 'Internal server error' });
 }
 ```
 
-### 4. Router Organization
+### Validation Middleware
 
 ```typescript
-// src/routes/index.ts
-import { Router } from 'express';
-import { userRouter } from './users';
-import { authRouter } from './auth';
-import { projectRouter } from './projects';
-import { organizationRouter } from './organizations';
-
-export const apiRouter = Router();
-
-apiRouter.use('/auth', authRouter);
-apiRouter.use('/users', userRouter);
-apiRouter.use('/organizations', organizationRouter);
-apiRouter.use('/projects', projectRouter);
-
-// src/routes/users.ts
-import { Router } from 'express';
-import { UserController } from '../controllers/UserController';
-import { authenticate, authorize } from '../middleware/auth';
-import { validate } from '../middleware/validate';
-import { userSchemas } from '../schemas/userSchemas';
-
-export const userRouter = Router();
-const controller = new UserController();
-
-userRouter.get(
-  '/',
-  authenticate(),
-  authorize('admin'),
-  validate({ query: userSchemas.list }),
-  controller.list
-);
-
-userRouter.get(
-  '/me',
-  authenticate(),
-  controller.getCurrentUser
-);
-
-userRouter.patch(
-  '/me',
-  authenticate(),
-  validate({ body: userSchemas.updateProfile }),
-  controller.updateProfile
-);
-
-userRouter.get(
-  '/:id',
-  authenticate(),
-  validate({ params: userSchemas.params }),
-  controller.getById
-);
-
-userRouter.post(
-  '/',
-  authenticate(),
-  authorize('admin'),
-  validate({ body: userSchemas.create }),
-  controller.create
-);
-
-userRouter.patch(
-  '/:id',
-  authenticate(),
-  authorize('admin'),
-  validate({ params: userSchemas.params, body: userSchemas.update }),
-  controller.update
-);
-
-userRouter.delete(
-  '/:id',
-  authenticate(),
-  authorize('admin'),
-  validate({ params: userSchemas.params }),
-  controller.delete
-);
-
-// src/routes/projects.ts
-import { Router } from 'express';
-import { ProjectController } from '../controllers/ProjectController';
-import { authenticate } from '../middleware/auth';
-import { validate } from '../middleware/validate';
-import { projectSchemas } from '../schemas/projectSchemas';
-import { cache } from '../middleware/cache';
-
-export const projectRouter = Router();
-const controller = new ProjectController();
-
-projectRouter.use(authenticate());
-
-projectRouter.get(
-  '/',
-  validate({ query: projectSchemas.list }),
-  cache({ ttl: 60 }),
-  controller.list
-);
-
-projectRouter.get(
-  '/:id',
-  validate({ params: projectSchemas.params }),
-  cache({ ttl: 300 }),
-  controller.getById
-);
-
-projectRouter.post(
-  '/',
-  validate({ body: projectSchemas.create }),
-  controller.create
-);
-
-projectRouter.patch(
-  '/:id',
-  validate({ params: projectSchemas.params, body: projectSchemas.update }),
-  controller.update
-);
-
-projectRouter.delete(
-  '/:id',
-  validate({ params: projectSchemas.params }),
-  controller.delete
-);
-
-// Nested routes for project tasks
-projectRouter.get(
-  '/:id/tasks',
-  validate({ params: projectSchemas.params, query: projectSchemas.taskList }),
-  controller.getTasks
-);
-
-projectRouter.post(
-  '/:id/tasks',
-  validate({ params: projectSchemas.params, body: projectSchemas.createTask }),
-  controller.createTask
-);
-```
-
-### 5. Controllers and Services
-
-```typescript
-// src/controllers/UserController.ts
-import { Response, NextFunction } from 'express';
-import { AuthRequest } from '../middleware/auth';
-import { UserService } from '../services/UserService';
-import { NotFoundError } from '../errors/AppError';
-
-export class UserController {
-  private userService = new UserService();
-
-  list = async (req: AuthRequest, res: Response, next: NextFunction) => {
-    try {
-      const { page = 1, limit = 20, search, role } = req.query as {
-        page?: number;
-        limit?: number;
-        search?: string;
-        role?: string;
-      };
-
-      const result = await this.userService.findAll({
-        page: Number(page),
-        limit: Math.min(Number(limit), 100),
-        search,
-        role,
-      });
-
-      res.json(result);
-    } catch (error) {
-      next(error);
-    }
-  };
-
-  getCurrentUser = async (req: AuthRequest, res: Response, next: NextFunction) => {
-    try {
-      const user = await this.userService.findById(req.user!.id);
-      if (!user) {
-        throw new NotFoundError('User');
-      }
-      res.json(user);
-    } catch (error) {
-      next(error);
-    }
-  };
-
-  getById = async (req: AuthRequest, res: Response, next: NextFunction) => {
-    try {
-      const user = await this.userService.findById(req.params.id);
-      if (!user) {
-        throw new NotFoundError('User', req.params.id);
-      }
-      res.json(user);
-    } catch (error) {
-      next(error);
-    }
-  };
-
-  create = async (req: AuthRequest, res: Response, next: NextFunction) => {
-    try {
-      const user = await this.userService.create(req.body);
-      res.status(201).json(user);
-    } catch (error) {
-      next(error);
-    }
-  };
-
-  updateProfile = async (req: AuthRequest, res: Response, next: NextFunction) => {
-    try {
-      const user = await this.userService.update(req.user!.id, req.body);
-      res.json(user);
-    } catch (error) {
-      next(error);
-    }
-  };
-
-  update = async (req: AuthRequest, res: Response, next: NextFunction) => {
-    try {
-      const user = await this.userService.update(req.params.id, req.body);
-      res.json(user);
-    } catch (error) {
-      next(error);
-    }
-  };
-
-  delete = async (req: AuthRequest, res: Response, next: NextFunction) => {
-    try {
-      await this.userService.delete(req.params.id);
-      res.status(204).send();
-    } catch (error) {
-      next(error);
-    }
-  };
-}
-
-// src/services/UserService.ts
-import { Prisma } from '@prisma/client';
-import { prisma } from '../database/prisma';
-import { ConflictError, NotFoundError } from '../errors/AppError';
-import { hashPassword, verifyPassword } from '../utils/password';
-
-interface FindAllOptions {
-  page: number;
-  limit: number;
-  search?: string;
-  role?: string;
-}
-
-interface CreateUserData {
-  email: string;
-  password: string;
-  name: string;
-  role?: string;
-}
-
-interface UpdateUserData {
-  email?: string;
-  name?: string;
-  role?: string;
-  password?: string;
-}
-
-export class UserService {
-  async findAll(options: FindAllOptions) {
-    const { page, limit, search, role } = options;
-    const skip = (page - 1) * limit;
-
-    const where: Prisma.UserWhereInput = {
-      deletedAt: null,
-      ...(search && {
-        OR: [
-          { name: { contains: search, mode: 'insensitive' } },
-          { email: { contains: search, mode: 'insensitive' } },
-        ],
-      }),
-      ...(role && { role }),
-    };
-
-    const [users, total] = await Promise.all([
-      prisma.user.findMany({
-        where,
-        skip,
-        take: limit,
-        select: {
-          id: true,
-          email: true,
-          name: true,
-          role: true,
-          createdAt: true,
-        },
-        orderBy: { createdAt: 'desc' },
-      }),
-      prisma.user.count({ where }),
-    ]);
-
-    return {
-      data: users,
-      pagination: {
-        page,
-        limit,
-        total,
-        totalPages: Math.ceil(total / limit),
-        hasMore: skip + users.length < total,
-      },
-    };
-  }
-
-  async findById(id: string) {
-    return prisma.user.findFirst({
-      where: { id, deletedAt: null },
-      select: {
-        id: true,
-        email: true,
-        name: true,
-        role: true,
-        createdAt: true,
-        updatedAt: true,
-        organizations: {
-          select: {
-            organization: {
-              select: { id: true, name: true, slug: true },
-            },
-            role: true,
-          },
-        },
-      },
-    });
-  }
-
-  async findByEmail(email: string) {
-    return prisma.user.findFirst({
-      where: { email, deletedAt: null },
-    });
-  }
-
-  async create(data: CreateUserData) {
-    const existing = await this.findByEmail(data.email);
-    if (existing) {
-      throw new ConflictError('Email already in use');
-    }
-
-    const hashedPassword = await hashPassword(data.password);
-
-    return prisma.user.create({
-      data: {
-        ...data,
-        password: hashedPassword,
-      },
-      select: {
-        id: true,
-        email: true,
-        name: true,
-        role: true,
-        createdAt: true,
-      },
-    });
-  }
-
-  async update(id: string, data: UpdateUserData) {
-    const user = await this.findById(id);
-    if (!user) {
-      throw new NotFoundError('User', id);
-    }
-
-    if (data.email && data.email !== user.email) {
-      const existing = await this.findByEmail(data.email);
-      if (existing) {
-        throw new ConflictError('Email already in use');
-      }
-    }
-
-    const updateData: Prisma.UserUpdateInput = { ...data };
-    if (data.password) {
-      updateData.password = await hashPassword(data.password);
-    }
-
-    return prisma.user.update({
-      where: { id },
-      data: updateData,
-      select: {
-        id: true,
-        email: true,
-        name: true,
-        role: true,
-        updatedAt: true,
-      },
-    });
-  }
-
-  async delete(id: string) {
-    const user = await this.findById(id);
-    if (!user) {
-      throw new NotFoundError('User', id);
-    }
-
-    // Soft delete
-    await prisma.user.update({
-      where: { id },
-      data: { deletedAt: new Date() },
-    });
-  }
+// middleware/validate.ts
+import { Request, Response, NextFunction } from 'express';
+import { ZodSchema } from 'zod';
 
-  async verifyCredentials(email: string, password: string) {
-    const user = await prisma.user.findFirst({
-      where: { email, deletedAt: null },
+export function validate(schema: ZodSchema) {
+  return (req: Request, res: Response, next: NextFunction) => {
+    const result = schema.safeParse({
+      body: req.body,
+      query: req.query,
+      params: req.params,
     });
 
-    if (!user) {
-      return null;
-    }
-
-    const isValid = await verifyPassword(password, user.password);
-    if (!isValid) {
-      return null;
+    if (!result.success) {
+      return res.status(400).json({ errors: result.error.issues });
     }
 
-    return {
-      id: user.id,
-      email: user.email,
-      name: user.name,
-      role: user.role,
-    };
-  }
+    next();
+  };
 }
 ```
 
-### 6. Validation Schemas
+## Workflows
 
-```typescript
-// src/schemas/userSchemas.ts
-import { z } from 'zod';
+### API Development Workflow
 
-export const userSchemas = {
-  params: z.object({
-    id: z.string().uuid('Invalid user ID'),
-  }),
+1. Define routes in `routes/index.ts`
+2. Create controller with business logic
+3. Add validation schemas with Zod
+4. Write tests with supertest
+5. Document with OpenAPI/Swagger
 
-  list: z.object({
-    page: z.coerce.number().int().positive().default(1),
-    limit: z.coerce.number().int().positive().max(100).default(20),
-    search: z.string().optional(),
-    role: z.enum(['admin', 'user', 'guest']).optional(),
-  }),
+### Middleware Order
 
-  create: z.object({
-    email: z.string().email('Invalid email address'),
-    password: z
-      .string()
-      .min(8, 'Password must be at least 8 characters')
-      .regex(/[A-Z]/, 'Password must contain an uppercase letter')
-      .regex(/[0-9]/, 'Password must contain a number'),
-    name: z.string().min(2).max(100),
-    role: z.enum(['admin', 'user', 'guest']).default('user'),
-  }),
-
-  update: z.object({
-    email: z.string().email('Invalid email address').optional(),
-    name: z.string().min(2).max(100).optional(),
-    role: z.enum(['admin', 'user', 'guest']).optional(),
-    password: z
-      .string()
-      .min(8, 'Password must be at least 8 characters')
-      .regex(/[A-Z]/, 'Password must contain an uppercase letter')
-      .regex(/[0-9]/, 'Password must contain a number')
-      .optional(),
-  }).refine(data => Object.keys(data).length > 0, {
-    message: 'At least one field must be provided',
-  }),
-
-  updateProfile: z.object({
-    name: z.string().min(2).max(100).optional(),
-    avatar: z.string().url().optional(),
-  }),
-};
-
-// src/schemas/projectSchemas.ts
-import { z } from 'zod';
-
-export const projectSchemas = {
-  params: z.object({
-    id: z.string().uuid('Invalid project ID'),
-  }),
-
-  list: z.object({
-    page: z.coerce.number().int().positive().default(1),
-    limit: z.coerce.number().int().positive().max(100).default(20),
-    status: z.enum(['draft', 'active', 'completed', 'archived']).optional(),
-    search: z.string().optional(),
-    sortBy: z.enum(['createdAt', 'name', 'updatedAt']).default('createdAt'),
-    sortOrder: z.enum(['asc', 'desc']).default('desc'),
-  }),
-
-  create: z.object({
-    name: z.string().min(1).max(255),
-    description: z.string().max(5000).optional(),
-    organizationId: z.string().uuid(),
-  }),
-
-  update: z.object({
-    name: z.string().min(1).max(255).optional(),
-    description: z.string().max(5000).optional(),
-    status: z.enum(['draft', 'active', 'completed', 'archived']).optional(),
-  }),
-
-  taskList: z.object({
-    page: z.coerce.number().int().positive().default(1),
-    limit: z.coerce.number().int().positive().max(100).default(20),
-    status: z.enum(['todo', 'in_progress', 'done']).optional(),
-  }),
-
-  createTask: z.object({
-    title: z.string().min(1).max(255),
-    description: z.string().max(5000).optional(),
-    priority: z.enum(['low', 'medium', 'high']).default('medium'),
-    assigneeId: z.string().uuid().optional(),
-    dueDate: z.coerce.date().optional(),
-  }),
-};
 ```
-
-### 7. Testing Patterns
-
-```typescript
-// tests/setup.ts
-import { PrismaClient } from '@prisma/client';
-import { mockDeep, DeepMockProxy } from 'jest-mock-extended';
-
-export const prismaMock = mockDeep<PrismaClient>();
-
-jest.mock('../src/database/prisma', () => ({
-  prisma: prismaMock,
-}));
-
-beforeEach(() => {
-  jest.clearAllMocks();
-});
-
-// tests/integration/users.test.ts
-import request from 'supertest';
-import { createApp } from '../../src/app';
-import { prisma } from '../../src/database/prisma';
-import { generateToken } from '../../src/utils/jwt';
-
-const app = createApp();
-
-describe('Users API', () => {
-  let adminToken: string;
-  let userToken: string;
-
-  beforeAll(async () => {
-    // Create test users
-    const admin = await prisma.user.create({
-      data: {
-        email: 'admin@test.com',
-        password: await hashPassword('Admin123!'),
-        name: 'Admin User',
-        role: 'admin',
-      },
-    });
-
-    const user = await prisma.user.create({
-      data: {
-        email: 'user@test.com',
-        password: await hashPassword('User123!'),
-        name: 'Regular User',
-        role: 'user',
-      },
-    });
-
-    adminToken = generateToken(admin);
-    userToken = generateToken(user);
-  });
-
-  afterAll(async () => {
-    await prisma.user.deleteMany();
-  });
-
-  describe('GET /api/v1/users', () => {
-    it('should return paginated users for admin', async () => {
-      const response = await request(app)
-        .get('/api/v1/users')
-        .set('Authorization', `Bearer ${adminToken}`)
-        .expect(200);
-
-      expect(response.body).toHaveProperty('data');
-      expect(response.body).toHaveProperty('pagination');
-      expect(Array.isArray(response.body.data)).toBe(true);
-    });
-
-    it('should return 403 for non-admin users', async () => {
-      await request(app)
-        .get('/api/v1/users')
-        .set('Authorization', `Bearer ${userToken}`)
-        .expect(403);
-    });
-
-    it('should return 401 without token', async () => {
-      await request(app)
-        .get('/api/v1/users')
-        .expect(401);
-    });
-
-    it('should filter users by search term', async () => {
-      const response = await request(app)
-        .get('/api/v1/users?search=admin')
-        .set('Authorization', `Bearer ${adminToken}`)
-        .expect(200);
-
-      expect(response.body.data.every((u: any) =>
-        u.name.toLowerCase().includes('admin') ||
-        u.email.toLowerCase().includes('admin')
-      )).toBe(true);
-    });
-  });
-
-  describe('GET /api/v1/users/me', () => {
-    it('should return current user profile', async () => {
-      const response = await request(app)
-        .get('/api/v1/users/me')
-        .set('Authorization', `Bearer ${userToken}`)
-        .expect(200);
-
-      expect(response.body.email).toBe('user@test.com');
-      expect(response.body).not.toHaveProperty('password');
-    });
-  });
-
-  describe('POST /api/v1/users', () => {
-    it('should create a new user', async () => {
-      const newUser = {
-        email: 'new@test.com',
-        password: 'NewUser123!',
-        name: 'New User',
-        role: 'user',
-      };
-
-      const response = await request(app)
-        .post('/api/v1/users')
-        .set('Authorization', `Bearer ${adminToken}`)
-        .send(newUser)
-        .expect(201);
-
-      expect(response.body.email).toBe(newUser.email);
-      expect(response.body).toHaveProperty('id');
-      expect(response.body).not.toHaveProperty('password');
-    });
-
-    it('should return 400 for invalid email', async () => {
-      const response = await request(app)
-        .post('/api/v1/users')
-        .set('Authorization', `Bearer ${adminToken}`)
-        .send({
-          email: 'invalid-email',
-          password: 'Valid123!',
-          name: 'Test User',
-        })
-        .expect(400);
-
-      expect(response.body.error.code).toBe('VALIDATION_ERROR');
-    });
-
-    it('should return 409 for duplicate email', async () => {
-      await request(app)
-        .post('/api/v1/users')
-        .set('Authorization', `Bearer ${adminToken}`)
-        .send({
-          email: 'user@test.com',
-          password: 'Duplicate123!',
-          name: 'Duplicate User',
-        })
-        .expect(409);
-    });
-  });
-});
-
-// tests/unit/UserService.test.ts
-import { UserService } from '../../src/services/UserService';
-import { prismaMock } from '../setup';
-
-describe('UserService', () => {
-  const service = new UserService();
-
-  describe('findAll', () => {
-    it('should return paginated users', async () => {
-      const mockUsers = [
-        { id: '1', email: 'user1@test.com', name: 'User 1', role: 'user', createdAt: new Date() },
-        { id: '2', email: 'user2@test.com', name: 'User 2', role: 'user', createdAt: new Date() },
-      ];
-
-      prismaMock.user.findMany.mockResolvedValue(mockUsers);
-      prismaMock.user.count.mockResolvedValue(2);
-
-      const result = await service.findAll({ page: 1, limit: 10 });
-
-      expect(result.data).toHaveLength(2);
-      expect(result.pagination.total).toBe(2);
-      expect(prismaMock.user.findMany).toHaveBeenCalledWith(
-        expect.objectContaining({
-          skip: 0,
-          take: 10,
-        })
-      );
-    });
-
-    it('should apply search filter', async () => {
-      prismaMock.user.findMany.mockResolvedValue([]);
-      prismaMock.user.count.mockResolvedValue(0);
-
-      await service.findAll({ page: 1, limit: 10, search: 'john' });
-
-      expect(prismaMock.user.findMany).toHaveBeenCalledWith(
-        expect.objectContaining({
-          where: expect.objectContaining({
-            OR: expect.arrayContaining([
-              { name: { contains: 'john', mode: 'insensitive' } },
-            ]),
-          }),
-        })
-      );
-    });
-  });
-
-  describe('create', () => {
-    it('should create a new user with hashed password', async () => {
-      const userData = {
-        email: 'new@test.com',
-        password: 'Password123!',
-        name: 'New User',
-      };
-
-      prismaMock.user.findFirst.mockResolvedValue(null);
-      prismaMock.user.create.mockResolvedValue({
-        id: 'new-id',
-        ...userData,
-        password: 'hashed',
-        role: 'user',
-        createdAt: new Date(),
-      });
-
-      const result = await service.create(userData);
-
-      expect(result.email).toBe(userData.email);
-      expect(prismaMock.user.create).toHaveBeenCalledWith(
-        expect.objectContaining({
-          data: expect.objectContaining({
-            email: userData.email,
-            password: expect.not.stringContaining(userData.password),
-          }),
-        })
-      );
-    });
-  });
-});
+1. Security (helmet, cors)
+2. Rate limiting
+3. Body parsing
+4. Logging
+5. Authentication
+6. Routes
+7. 404 handler
+8. Error handler
 ```
 
-## Use Cases
-
-### REST API for E-commerce Platform
-
-```typescript
-// src/routes/products.ts
-import { Router } from 'express';
-import { ProductController } from '../controllers/ProductController';
-import { authenticate, authorize } from '../middleware/auth';
-import { validate } from '../middleware/validate';
-import { cache } from '../middleware/cache';
-import { upload } from '../middleware/upload';
-import { z } from 'zod';
-
-const router = Router();
-const controller = new ProductController();
-
-const productSchemas = {
-  list: z.object({
-    category: z.string().optional(),
-    minPrice: z.coerce.number().positive().optional(),
-    maxPrice: z.coerce.number().positive().optional(),
-    search: z.string().optional(),
-    sortBy: z.enum(['price', 'name', 'createdAt', 'popularity']).default('createdAt'),
-    sortOrder: z.enum(['asc', 'desc']).default('desc'),
-    page: z.coerce.number().positive().default(1),
-    limit: z.coerce.number().positive().max(50).default(20),
-  }),
-  create: z.object({
-    name: z.string().min(1).max(255),
-    description: z.string().max(5000),
-    price: z.number().positive(),
-    categoryId: z.string().uuid(),
-    inventory: z.number().int().nonnegative().default(0),
-    sku: z.string().optional(),
-  }),
-};
-
-// Public routes
-router.get(
-  '/',
-  validate({ query: productSchemas.list }),
-  cache({ ttl: 60 }),
-  controller.list
-);
-
-router.get(
-  '/:id',
-  cache({ ttl: 300 }),
-  controller.getById
-);
+## Best Practices
 
-// Admin routes
-router.post(
-  '/',
-  authenticate(),
-  authorize('admin'),
-  upload.array('images', 5),
-  validate({ body: productSchemas.create }),
-  controller.create
-);
+| Do | Avoid |
+|----|-------|
+| Use async/await with try-catch | Callback patterns |
+| Validate all inputs | Trusting client data |
+| Use typed request/response | `any` types |
+| Centralize error handling | Scattered try-catch |
+| Use dependency injection | Direct imports in controllers |
 
-router.patch(
-  '/:id',
-  authenticate(),
-  authorize('admin'),
-  controller.update
-);
+## Project Structure
 
-export { router as productRouter };
 ```
-
-### WebSocket Integration for Real-time Updates
-
-```typescript
-// src/websocket/index.ts
-import { Server as SocketIOServer } from 'socket.io';
-import { Server } from 'http';
-import { verifyToken } from '../utils/jwt';
-import { logger } from '../utils/logger';
-
-export function setupWebSocket(server: Server) {
-  const io = new SocketIOServer(server, {
-    cors: {
-      origin: process.env.CORS_ORIGINS?.split(',') || '*',
-      credentials: true,
-    },
-  });
-
-  // Authentication middleware
-  io.use(async (socket, next) => {
-    try {
-      const token = socket.handshake.auth.token;
-      if (!token) {
-        return next(new Error('Authentication required'));
-      }
-
-      const user = await verifyToken(token);
-      socket.data.user = user;
-      next();
-    } catch (error) {
-      next(new Error('Invalid token'));
-    }
-  });
-
-  io.on('connection', (socket) => {
-    const user = socket.data.user;
-    logger.info(`User connected: ${user.id}`);
-
-    // Join user's personal room
-    socket.join(`user:${user.id}`);
-
-    // Join organization rooms
-    socket.on('join:organization', async (orgId: string) => {
-      // Verify user belongs to organization
-      const membership = await checkMembership(user.id, orgId);
-      if (membership) {
-        socket.join(`org:${orgId}`);
-        socket.emit('joined:organization', { orgId });
-      }
-    });
-
-    // Handle real-time notifications
-    socket.on('disconnect', () => {
-      logger.info(`User disconnected: ${user.id}`);
-    });
-  });
-
-  return io;
-}
-
-// Emit events from services
-export function emitToUser(io: SocketIOServer, userId: string, event: string, data: unknown) {
-  io.to(`user:${userId}`).emit(event, data);
-}
-
-export function emitToOrganization(io: SocketIOServer, orgId: string, event: string, data: unknown) {
-  io.to(`org:${orgId}`).emit(event, data);
-}
+src/
+├── app.ts              # Express setup
+├── server.ts           # Server entry
+├── config/             # Environment config
+├── controllers/        # Route handlers
+├── middleware/         # Custom middleware
+├── routes/             # Route definitions
+├── services/           # Business logic
+├── utils/              # Helpers
+└── types/              # TypeScript types
 ```
 
-## Best Practices
-
-### Do's
-
-- Use TypeScript for type safety
-- Implement proper error handling with custom error classes
-- Use validation middleware for all inputs
-- Use dependency injection for testability
-- Implement proper logging with correlation IDs
-- Use environment variables for configuration
-- Implement graceful shutdown handling
-- Use compression and rate limiting
-- Write integration and unit tests
-- Use async/await consistently
-
-### Don'ts
-
-- Don't use callbacks when async/await is available
-- Don't catch errors without proper handling
-- Don't expose stack traces in production
-- Don't store secrets in code
-- Don't skip input validation
-- Don't use synchronous file operations
-- Don't ignore error handling in middleware
-- Don't use `any` type unnecessarily
-- Don't forget to handle promise rejections
-- Don't skip security headers
-
-## References
-
-- [Express.js Documentation](https://expressjs.com/)
-- [Node.js Best Practices](https://github.com/goldbergyoni/nodebestpractices)
-- [Prisma Documentation](https://www.prisma.io/docs)
-- [Zod Documentation](https://zod.dev/)
-- [TypeScript Express Tutorial](https://developer.okta.com/blog/2018/11/15/node-express-typescript)
+For detailed examples and patterns, see reference files above.