147 lines
5.1 KiB
Markdown
147 lines
5.1 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Project Overview
|
|
|
|
MX Space is a personal blog server application built with NestJS, MongoDB, and Redis. This is a monorepo containing the core server application and related packages. The main application is located in `apps/core/`.
|
|
|
|
## Development Commands
|
|
|
|
All commands should be run from the repository root unless specified otherwise.
|
|
|
|
### Core Development Commands
|
|
- `pnpm dev` - Start development server (builds externals then starts core app)
|
|
- `pnpm build` - Build the entire project (externals + core)
|
|
- `pnpm bundle` - Create production bundle
|
|
- `pnpm test` - Run tests
|
|
- `pnpm lint` - Run ESLint on core app
|
|
- `pnpm format` - Format code with Prettier
|
|
|
|
### Core App Specific Commands (run from `apps/core/`)
|
|
- `npm run start` - Start development server with watch mode
|
|
- `npm run start:cluster` - Start in cluster mode with 2 workers
|
|
- `npm run start:debug` - Start with debug mode
|
|
- `npm run repl` - Start REPL mode
|
|
- `npm run test:watch` - Run tests in watch mode
|
|
- `npm run build:webpack` - Build with webpack (alternative build method)
|
|
|
|
## Architecture Overview
|
|
|
|
### Directory Structure
|
|
- `apps/core/` - Main NestJS application
|
|
- `src/modules/` - Business logic modules (auth, posts, comments, etc.)
|
|
- `src/processors/` - Infrastructure services (database, redis, gateway, helpers)
|
|
- `src/common/` - Shared utilities (guards, interceptors, decorators, etc.)
|
|
- `src/migration/` - Database migration scripts
|
|
- `test/` - Test files and mocks
|
|
- `packages/` - Shared packages
|
|
- `external/` - External dependencies with custom implementations
|
|
|
|
### Key Architectural Patterns
|
|
|
|
**Modular Design**: Each business domain has its own module (posts, comments, auth, etc.) with controllers, services, DTOs, and models.
|
|
|
|
**Processors**: Infrastructure services are organized in `processors/`:
|
|
- `database/` - MongoDB connection and models
|
|
- `redis/` - Redis caching and pub/sub
|
|
- `gateway/` - WebSocket gateways for real-time features
|
|
- `helper/` - Utility services (email, image processing, etc.)
|
|
|
|
**Common Layer**: Shared functionality in `src/common/`:
|
|
- Guards for authentication and authorization
|
|
- Interceptors for response transformation, caching, and logging
|
|
- Decorators for common patterns
|
|
- Exception filters
|
|
|
|
### Database Models
|
|
Uses Mongoose with TypeGoose for type-safe MongoDB models. All models extend a base model with common fields like `_id`, `created`, `updated`.
|
|
|
|
### Authentication
|
|
JWT-based authentication with role-based access control. Uses decorators like `@Auth()` and `@CurrentUser()` for protection.
|
|
|
|
### Caching Strategy
|
|
Redis-based caching with cache interceptors. Uses conditional caching based on request patterns.
|
|
|
|
## Configuration
|
|
|
|
The application uses a command-line interface for configuration (`src/app.config.ts`). Key configuration includes:
|
|
- Database connection (MongoDB)
|
|
- Redis configuration
|
|
- JWT settings
|
|
- CORS settings
|
|
- Cluster mode options
|
|
|
|
Configuration can be provided via:
|
|
- Environment variables
|
|
- Command line arguments
|
|
- YAML configuration files
|
|
|
|
## Testing
|
|
|
|
Uses Vitest for testing with:
|
|
- E2E tests for controllers
|
|
- Unit tests for services and utilities
|
|
- Mock implementations for external dependencies
|
|
- In-memory MongoDB and Redis for testing
|
|
|
|
Test files are located in `test/` directory with mocks in `test/mock/`.
|
|
|
|
## Development Patterns
|
|
|
|
### Controllers
|
|
- Use `@ApiController()` decorator for API controllers
|
|
- Implement proper DTOs for request/response validation
|
|
- Use guards and interceptors for cross-cutting concerns
|
|
|
|
### Services
|
|
- Implement business logic in services
|
|
- Use dependency injection for database and external services
|
|
- Handle errors appropriately with custom exceptions
|
|
|
|
### Models
|
|
- Use TypeGoose for MongoDB models
|
|
- Implement proper indexes and relationships
|
|
- Use plugins for common functionality (pagination, auto-increment)
|
|
|
|
### DTOs
|
|
- Use class-validator for input validation
|
|
- Implement proper transformation decorators
|
|
- Group related DTOs by module
|
|
|
|
## Build and Deployment
|
|
|
|
The application supports multiple build methods:
|
|
- Standard NestJS build (`nest build`)
|
|
- Webpack build for optimized bundles
|
|
- Bundle script for production deployment
|
|
|
|
Deployment uses PM2 with ecosystem configuration files for cluster management.
|
|
|
|
## Key Dependencies
|
|
|
|
- **NestJS** - Main framework
|
|
- **Mongoose/TypeGoose** - MongoDB ODM
|
|
- **Fastify** - HTTP server (instead of Express)
|
|
- **Redis** - Caching and pub/sub
|
|
- **Socket.IO** - WebSocket support
|
|
- **class-validator** - Input validation
|
|
- **Vitest** - Testing framework
|
|
|
|
## Common Development Tasks
|
|
|
|
### Adding a New Module
|
|
1. Create module directory in `src/modules/`
|
|
2. Implement controller, service, model, and DTOs
|
|
3. Add module to `app.module.ts`
|
|
4. Write tests in corresponding test directory
|
|
|
|
### Database Migrations
|
|
- Migration scripts located in `src/migration/version/`
|
|
- Use helper functions for common migration tasks
|
|
- Version migrations by application version
|
|
|
|
### Adding Tests
|
|
- Create test files with `.spec.ts` or `.e2e-spec.ts` suffix
|
|
- Use mock helpers from `test/helper/`
|
|
- Use test setup files for common configuration |