147
CLAUDE.md
Normal file
147
CLAUDE.md
Normal file
@@ -0,0 +1,147 @@
|
|||||||
|
# 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
|
||||||
@@ -50,10 +50,10 @@
|
|||||||
"dependencies": {
|
"dependencies": {
|
||||||
"@ai-sdk/openai": "1.3.23",
|
"@ai-sdk/openai": "1.3.23",
|
||||||
"@algolia/client-search": "^4.22.1",
|
"@algolia/client-search": "^4.22.1",
|
||||||
"@babel/core": "7.28.0",
|
"@babel/core": "7.28.3",
|
||||||
"@babel/plugin-transform-modules-commonjs": "7.27.1",
|
"@babel/plugin-transform-modules-commonjs": "7.27.1",
|
||||||
"@babel/plugin-transform-typescript": "7.28.0",
|
"@babel/plugin-transform-typescript": "7.28.0",
|
||||||
"@babel/types": "^7.28.0",
|
"@babel/types": "^7.28.2",
|
||||||
"@fastify/cookie": "11.0.2",
|
"@fastify/cookie": "11.0.2",
|
||||||
"@fastify/multipart": "9.0.3",
|
"@fastify/multipart": "9.0.3",
|
||||||
"@fastify/static": "8.2.0",
|
"@fastify/static": "8.2.0",
|
||||||
@@ -62,15 +62,15 @@
|
|||||||
"@keyv/redis": "4.6.0",
|
"@keyv/redis": "4.6.0",
|
||||||
"@mx-space/compiled": "workspace:*",
|
"@mx-space/compiled": "workspace:*",
|
||||||
"@nestjs/cache-manager": "3.0.1",
|
"@nestjs/cache-manager": "3.0.1",
|
||||||
"@nestjs/common": "11.1.3",
|
"@nestjs/common": "11.1.6",
|
||||||
"@nestjs/core": "11.1.3",
|
"@nestjs/core": "11.1.6",
|
||||||
"@nestjs/event-emitter": "3.0.1",
|
"@nestjs/event-emitter": "3.0.1",
|
||||||
"@nestjs/mapped-types": "^2.1.0",
|
"@nestjs/mapped-types": "^2.1.0",
|
||||||
"@nestjs/platform-fastify": "11.1.3",
|
"@nestjs/platform-fastify": "11.1.6",
|
||||||
"@nestjs/platform-socket.io": "11.1.3",
|
"@nestjs/platform-socket.io": "11.1.6",
|
||||||
"@nestjs/schedule": "6.0.0",
|
"@nestjs/schedule": "6.0.0",
|
||||||
"@nestjs/throttler": "6.4.0",
|
"@nestjs/throttler": "6.4.0",
|
||||||
"@nestjs/websockets": "11.1.3",
|
"@nestjs/websockets": "11.1.6",
|
||||||
"@simplewebauthn/server": "10.0.1",
|
"@simplewebauthn/server": "10.0.1",
|
||||||
"@socket.io/redis-adapter": "8.3.0",
|
"@socket.io/redis-adapter": "8.3.0",
|
||||||
"@socket.io/redis-emitter": "5.1.0",
|
"@socket.io/redis-emitter": "5.1.0",
|
||||||
@@ -131,10 +131,10 @@
|
|||||||
"zx-cjs": "7.0.7-0"
|
"zx-cjs": "7.0.7-0"
|
||||||
},
|
},
|
||||||
"devDependencies": {
|
"devDependencies": {
|
||||||
"@nestjs/cli": "11.0.7",
|
"@nestjs/cli": "11.0.10",
|
||||||
"@nestjs/schematics": "11.0.5",
|
"@nestjs/schematics": "11.0.7",
|
||||||
"@nestjs/testing": "11.1.3",
|
"@nestjs/testing": "11.1.6",
|
||||||
"@swc/core": "1.12.11",
|
"@swc/core": "1.13.5",
|
||||||
"@types/babel__core": "7.20.5",
|
"@types/babel__core": "7.20.5",
|
||||||
"@types/bcryptjs": "^3.0.0",
|
"@types/bcryptjs": "^3.0.0",
|
||||||
"@types/cls-hooked": "^4.3.9",
|
"@types/cls-hooked": "^4.3.9",
|
||||||
@@ -144,7 +144,7 @@
|
|||||||
"@types/lodash": "4.17.20",
|
"@types/lodash": "4.17.20",
|
||||||
"@types/mime-types": "3.0.1",
|
"@types/mime-types": "3.0.1",
|
||||||
"@types/mongoose-aggregate-paginate-v2": "1.1.2",
|
"@types/mongoose-aggregate-paginate-v2": "1.1.2",
|
||||||
"@types/node": "24.0.12",
|
"@types/node": "24.3.0",
|
||||||
"@types/nodemailer": "6.4.17",
|
"@types/nodemailer": "6.4.17",
|
||||||
"@types/qs": "6.14.0",
|
"@types/qs": "6.14.0",
|
||||||
"@types/remove-markdown": "0.3.4",
|
"@types/remove-markdown": "0.3.4",
|
||||||
@@ -152,14 +152,14 @@
|
|||||||
"@types/ua-parser-js": "0.7.39",
|
"@types/ua-parser-js": "0.7.39",
|
||||||
"@types/validator": "13.15.2",
|
"@types/validator": "13.15.2",
|
||||||
"@vercel/ncc": "0.38.3",
|
"@vercel/ncc": "0.38.3",
|
||||||
"ioredis": "5.6.1",
|
"ioredis": "5.7.0",
|
||||||
"mongodb-memory-server": "^10.1.4",
|
"mongodb-memory-server": "^10.2.0",
|
||||||
"redis-memory-server": "^0.12.1",
|
"redis-memory-server": "^0.12.1",
|
||||||
"rimraf": "6.0.1",
|
"rimraf": "6.0.1",
|
||||||
"sharp": "0.34.3",
|
"sharp": "0.34.3",
|
||||||
"socket.io": "^4.8.1",
|
"socket.io": "^4.8.1",
|
||||||
"typescript": "5.8.3",
|
"typescript": "5.8.3",
|
||||||
"unplugin-swc": "1.5.5",
|
"unplugin-swc": "1.5.7",
|
||||||
"vite": "5.4.10",
|
"vite": "5.4.10",
|
||||||
"vite-tsconfig-paths": "5.1.4",
|
"vite-tsconfig-paths": "5.1.4",
|
||||||
"vitest": "1.5.2"
|
"vitest": "1.5.2"
|
||||||
|
|||||||
1970
pnpm-lock.yaml
generated
1970
pnpm-lock.yaml
generated
File diff suppressed because it is too large
Load Diff
Reference in New Issue
Block a user