feat: add CLAUDE.md for project guidance and enhance file upload support in MagicRouter

Author: muneebhashone

CLAUDE.md

@@ -0,0 +1,68 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Development Commands
+
+- **Development server**: `pnpm run dev` - Starts both backend and email template development server
+- **Backend only**: `pnpm run start:dev` - Starts just the backend with hot reload
+- **Build**: `pnpm run build` - Builds the project using tsup
+- **Production start**: `pnpm run start:prod` - Starts production build with .env.production
+- **Local start**: `pnpm run start:local` - Starts production build with .env.local
+- **Database seeder**: `pnpm run seeder` - Runs database seeding scripts
+- **Linting**: `pnpm run lint` - Runs ESLint, `pnpm run lint:fix` - Auto-fixes linting issues
+- **Email templates**: `pnpm run email:dev` - Starts email template development server
+
+## Architecture Overview
+
+This is a TypeScript Express.js backend toolkit with the following key architectural components:
+
+### Core Architecture
+- **MagicRouter System**: Custom routing ([src/openapi/magic-router.ts](src/openapi/magic-router.ts)) that automatically generates OpenAPI/Swagger documentation from Zod schemas
+- **Module-based structure**: Features organized in modules under [src/modules/](src/modules/) (auth, user)
+- **Configuration management**: Type-safe config using Zod validation in [src/config/config.service.ts](src/config/config.service.ts)
+- **Database**: MongoDB with Mongoose ODM, connection managed in [src/lib/database.ts](src/lib/database.ts)
+
+### Key Features
+- **Authentication**: JWT-based with optional OTP verification, Google OAuth support
+- **File Uploads**: Multer with S3 integration via [src/lib/aws.service.ts](src/lib/aws.service.ts)
+- **Email System**: React Email templates with Mailgun provider, queue-based sending
+- **Real-time**: Socket.io integration with Redis adapter
+- **Background Jobs**: BullMQ with Redis for email queues and other background tasks
+- **API Documentation**: Auto-generated Swagger docs at `/api-docs` from MagicRouter
+- **Queue Dashboard**: BullMQ admin dashboard at `/admin/queues`
+
+### Middleware Stack
+- Request validation with Zod schemas ([src/middlewares/validate-zod-schema.middleware.ts](src/middlewares/validate-zod-schema.middleware.ts))
+- JWT extraction and authorization ([src/middlewares/extract-jwt-schema.middleware.ts](src/middlewares/extract-jwt-schema.middleware.ts))
+- File upload handling with S3 ([src/middlewares/multer-s3.middleware.ts](src/middlewares/multer-s3.middleware.ts))
+- Access control middleware ([src/middlewares/can-access.middleware.ts](src/middlewares/can-access.middleware.ts))
+
+### Environment Setup
+1. Start Docker services: `docker compose up -d` (MongoDB + Redis)
+2. Install dependencies: `pnpm i`
+3. Configure environment variables using `.env.sample` as template
+
+### Key Patterns
+- **MagicRouter**: All API routes use MagicRouter for automatic OpenAPI generation
+- **Zod Schemas**: Every route uses Zod for request/response validation
+- **Service Layer**: Business logic separated into service files
+- **Queue-based**: Email sending and background jobs use BullMQ queues
+- **Type Safety**: Full TypeScript coverage with Zod for runtime validation
+
+### File Upload & Storage
+- Multer middleware handles file uploads
+- AWS S3 integration for file storage
+- File upload routes in [src/upload/](src/upload/)
+
+### Email System
+- React Email for template development
+- Mailgun for email delivery
+- Queue-based sending system in [src/queues/email.queue.ts](src/queues/email.queue.ts)
+
+## Important Notes
+- All expiration times in config are in milliseconds (converted from strings)
+- The project uses pnpm as package manager
+- Database seeding is available via the seeder script
+- Global error handling in [src/utils/globalErrorHandler.ts](src/utils/globalErrorHandler.ts)
+- Logging uses Pino logger with pretty printing in development

README.md

@@ -24,12 +24,14 @@ Before you get started, make sure you have the following installed on your machi
      ```sh
      docker compose up -d
      ```
+
 2. **Install Dependencies**:
 
    - Use pnpm to install all the necessary dependencies:
      ```sh
      pnpm i
      ```
+
 3. **Configure Environment Variables**:
 
    - Create a `.env` file in the root directory.
@@ -40,7 +42,7 @@ Before you get started, make sure you have the following installed on your machi
 - **OpenAPI Autogenerated Swagger Docs** : Automatically generated Swagger docs through MagicRouter API and Zod, accessible at `/api-docs`.
 - **Auth Module**: Includes Google Sign-In support for easy authentication.
 - **User Management**: Comprehensive user management functionality.
-- **File Upload**: Handles file uploads with Multer and Amazon S3.
+- **File Upload**: Handles file uploads with Multer and Amazon S3, with full OpenAPI/Swagger documentation support.
 - **Data Validation & Serialization**: Zod is used for validation and serialization of data.
 - **Configuration Management**: Managed using dotenv-cli and validated with Zod for accuracy and safety.
 - **Middlewares**:
@@ -64,6 +66,7 @@ Before you get started, make sure you have the following installed on your machi
 - **PM2 Support**: Out-of-the-box support for PM2 to manage your production processes.
 
 ## Folder Structure
+
 ```plaintext
 ├── build.ts
 ├── docker-compose.yml
@@ -153,6 +156,93 @@ Before you get started, make sure you have the following installed on your machi
 └── tsconfig.json
 ```
 
+## File Upload with MagicRouter
+
+MagicRouter now supports multipart/form-data file uploads with automatic OpenAPI documentation generation. This feature works seamlessly with Multer middleware.
+
+### Usage
+
+#### Single File Upload
+
+```typescript
+import { z } from 'zod';
+import MagicRouter from './openapi/magic-router';
+import { zFile } from './openapi/zod-extend';
+import { uploadMiddleware } from './middlewares/multer-s3.middleware';
+
+const router = new MagicRouter('/api');
+
+router.post(
+  '/upload',
+  {
+    requestType: {
+      body: z.object({
+        avatar: zFile(),
+      }),
+    },
+    contentType: 'multipart/form-data',
+  },
+  uploadMiddleware,
+  handleUpload,
+);
+```
+
+#### Multiple Files Upload
+
+```typescript
+import { zFiles } from './openapi/zod-extend';
+
+router.post(
+  '/upload-multiple',
+  {
+    requestType: {
+      body: z.object({
+        images: zFiles(),
+      }),
+    },
+    contentType: 'multipart/form-data',
+  },
+  uploadMiddleware,
+  handleMultipleUpload,
+);
+```
+
+#### Mixed Fields (Text + Files)
+
+```typescript
+router.post(
+  '/upload-with-data',
+  {
+    requestType: {
+      body: z.object({
+        name: z.string(),
+        email: z.string().email(),
+        avatar: zFile(),
+        documents: zFiles().optional(),
+      }),
+    },
+    contentType: 'multipart/form-data',
+  },
+  uploadMiddleware,
+  handleUploadWithData,
+);
+```
+
+### Content Types
+
+MagicRouter supports three content types:
+
+- `application/json` (default)
+- `multipart/form-data` (for file uploads)
+- `application/x-www-form-urlencoded` (for form submissions)
+
+### Key Features
+
+- **Automatic OpenAPI Generation**: File upload endpoints are automatically documented in Swagger
+- **Multer Compatible**: Works with existing Multer middleware without changes
+- **Type-Safe**: Zod validation for text fields while Multer handles file validation
+- **Flexible**: Support for single files, multiple files, and mixed text/file fields
+
 ## Roadmap
 
 - **Socket.io Support:** Adding support for Redis adapter and a chat module.

src/middlewares/multer-s3.middleware.ts

@@ -1,49 +1,49 @@
-import type { NextFunction } from "express";
-import { StatusCodes } from "http-status-codes";
-import multer from "multer";
-import multerS3 from "multer-s3";
-import s3, { BUCKET_NAME } from "../lib/aws.service";
-import { errorResponse } from "../utils/api.utils";
-import { checkFiletype } from "../utils/common.utils";
-import type { RequestAny, ResponseAny } from "../openapi/magic-router";
+import type { NextFunction } from 'express';
+import { StatusCodes } from 'http-status-codes';
+import multer from 'multer';
+import multerS3 from 'multer-s3';
+import s3, { BUCKET_NAME } from '../lib/aws.service';
+import { errorResponse } from '../utils/api.utils';
+import { checkFiletype } from '../utils/common.utils';
+import type { RequestAny, ResponseAny } from '../openapi/magic-router';
 
 const storageEngineProfile: multer.StorageEngine = multerS3({
-	s3: s3,
-	bucket: BUCKET_NAME,
-	metadata: (_, file, cb) => {
-		cb(null, { fieldName: file.fieldname });
-	},
-	key: (req: RequestAny, file, cb) => {
-		const key = `user-${req.user.id}/profile/${file.originalname}`;
+  s3: s3,
+  bucket: BUCKET_NAME,
+  metadata: (_, file, cb) => {
+    cb(null, { fieldName: file.fieldname });
+  },
+  key: (req: RequestAny, file, cb) => {
+    const key = `user-${req.user.id}/profile/${file.originalname}`;
 
-		if (checkFiletype(file)) {
-			cb(null, key);
-		} else {
-			cb("File format is not valid", key);
-		}
-	},
+    if (checkFiletype(file)) {
+      cb(null, key);
+    } else {
+      cb('File format is not valid', key);
+    }
+  },
 });
 
 export const uploadProfile = (
-	req: RequestAny,
-	res: ResponseAny,
-	next: NextFunction,
+  req: RequestAny,
+  res: ResponseAny,
+  next?: NextFunction,
 ) => {
-	const upload = multer({
-		storage: storageEngineProfile,
-		limits: { fileSize: 1000000 * 10 },
-	}).single("avatar");
+  const upload = multer({
+    storage: storageEngineProfile,
+    limits: { fileSize: 1000000 * 10 },
+  }).single('avatar');
 
-	upload(req, res, (err) => {
-		if (err) {
-			return errorResponse(
-				res,
-				(err as Error).message,
-				StatusCodes.BAD_REQUEST,
-				err,
-			);
-		}
+  upload(req, res, (err) => {
+    if (err) {
+      return errorResponse(
+        res,
+        (err as Error).message,
+        StatusCodes.BAD_REQUEST,
+        err,
+      );
+    }
 
-		next();
-	});
+    next?.();
+  });
 };