@fecommunity/reactpress-server 1.0.0-beta.8 → 1.0.0

package/README.md

@@ -1,395 +1,367 @@
 # @fecommunity/reactpress-server
 
-NestJS-based backend API server for ReactPress - A modern React-based CMS platform.
+ReactPress Server - Enterprise-grade NestJS 10 backend API for ReactPress CMS with WordPress-style 5-minute installation.
 
-## Installation
+[![NPM Version](https://img.shields.io/npm/v/@fecommunity/reactpress-server.svg)](https://www.npmjs.com/package/@fecommunity/reactpress-server)
+[![License](https://img.shields.io/npm/l/@fecommunity/reactpress-server.svg)](https://github.com/fecommunity/reactpress/blob/master/server/LICENSE)
+[![Node Version](https://img.shields.io/node/v/@fecommunity/reactpress-server.svg)](https://nodejs.org)
+[![TypeScript](https://img.shields.io/badge/%3C%2F%3E-TypeScript-%230074c1.svg)](http://www.typescriptlang.org/)
+[![NestJS](https://img.shields.io/badge/NestJS-10-red)](https://nestjs.com/)
 
-```bash
-# For new projects
-npm install @fecommunity/reactpress-server@1.0.0-beta.1 @fecommunity/reactpress-config@1.0.0-beta.1
-
-# Using yarn
-yarn add @fecommunity/reactpress-server@1.0.0-beta.1 @fecommunity/reactpress-config@1.0.0-beta.1
-
-# Using pnpm in workspace root (add -w flag)
-pnpm add -w @fecommunity/reactpress-server@1.0.0-beta.1 @fecommunity/reactpress-config@1.0.0-beta.1
-
-# Using pnpm in standalone project
-pnpm add @fecommunity/reactpress-server@1.0.0-beta.1 @fecommunity/reactpress-config@1.0.0-beta.1
-```
+## Overview
 
-## Features
+ReactPress Server is an enterprise-grade, production-ready backend API built with NestJS 10 that powers the ReactPress CMS platform. It provides a comprehensive set of RESTful APIs for content management, user authentication, media handling, and more. With its WordPress-style 5-minute installation, it offers an incredibly smooth setup experience.
 
-- 🚀 **NestJS Framework** - Built on modern, scalable Node.js framework
-- 🔐 **Authentication & Authorization** - JWT-based auth with role management
-- 📝 **Content Management** - Full CRUD for articles, categories, tags, and comments
-- 🗃️ **Database Integration** - MySQL support with TypeORM
-- 📁 **File Upload** - Local and cloud storage support (Ali OSS)
-- 🌍 **Internationalization** - Multi-language support
-- 📚 **API Documentation** - Auto-generated Swagger docs
-- 🔒 **Security** - Rate limiting, CORS, Helmet integration
+The server is built with a modular architecture following NestJS best practices, making it highly extensible and maintainable. It automatically generates OpenAPI/Swagger documentation that powers the [ReactPress Toolkit](../toolkit), ensuring seamless frontend-backend integration.
 
 ## Quick Start
 
-### 1. Initialize Server
+### Installation & Setup
 
 ```bash
-# Using npx (recommended for first-time use)
-npx @fecommunity/reactpress-server init
+# Regular startup
+npx @fecommunity/reactpress-server
 
-# Or if installed globally
-reactpress-server init
+# PM2 startup for production
+npx @fecommunity/reactpress-server --pm2
 ```
 
-This will create configuration files and set up your environment.
-
-### 2. Start Development Server
-
+That's it! The command will automatically:
+
+1. **Auto-detect** if configuration exists
+2. **Launch installation wizard** in your browser if no configuration found
+3. **Start the server** immediately after installation
+4. **Open API documentation** at `http://localhost:3002/api`
+
+## Enterprise Features
+
+- 🚀 **Zero-Command Installation** - No complex CLI parameters needed
+- 🌍 **WordPress-Style Setup** - Familiar 5-minute installation process
+- 🔧 **Auto-Configuration** - Generates `.env` files automatically
+- 🔌 **Database Auto-Provisioning** - Creates MySQL database with migrations
+- 🎯 **Seamless Flow** - From installation to running server in minutes
+- 📖 **Auto-Documentation** - Swagger API docs available immediately
+- ⚡ **PM2 Support** - Optional PM2 process management for production
+- 🔐 **Enterprise Security** - JWT with refresh token rotation, rate limiting
+- 🛡️ **Advanced Security** - Helmet.js, CSRF protection, input validation
+- 📱 **Responsive APIs** - Mobile-friendly RESTful endpoints
+- 🌐 **Globalization** - Multi-language support with RTL
+- 📊 **Analytics Tracking** - Built-in view and visitor analytics
+- 🔄 **Data Synchronization** - Scheduled tasks and webhook support
+
+## Requirements
+
+- Node.js >= 18.20.4
+- MySQL 8.0+ or PostgreSQL 13+
+- npm or pnpm package manager
+
+## Usage Scenarios
+
+### Standalone API Server
+Perfect for:
+- Headless CMS implementation
+- Mobile app backend
+- Microservices architecture
+- Custom frontend integration
+- Enterprise API gateway
+
+### Full ReactPress Stack
+Use with ReactPress client for complete CMS solution:
 ```bash
-# Using npx
-npx @fecommunity/reactpress-server dev
+# Start server
+npx @fecommunity/reactpress-server
 
-# Or if installed globally
-reactpress-server dev
+# In another terminal, start client
+npx @fecommunity/reactpress-client
 ```
 
-The server will start on `http://localhost:3002` with API documentation at `http://localhost:3002/api`.
+## API Modules
 
-### 3. Start Production Server
+ReactPress Server provides comprehensive enterprise API modules:
 
-```bash
-# Using npx
-npx @fecommunity/reactpress-server start
+- **Article Management** - Create, read, update, delete articles with versioning
+- **User Authentication** - Registration, login, password management, 2FA
+- **Comment System** - Comment moderation and management with spam detection
+- **Media Management** - File upload and management (local/S3/Cloudinary)
+- **Category & Tag** - Content organization systems with hierarchy
+- **Page Management** - Custom page creation with templates
+- **Settings** - System configuration management with environment overrides
+- **SMTP** - Email sending capabilities with template system
+- **Search** - Full-text search functionality with Elasticsearch integration
+- **Analytics** - Visitor and view tracking with export capabilities
+- **Webhooks** - Event-driven integrations with external services
+- **Scheduled Tasks** - Cron jobs for automated operations
 
-# Or if installed globally
-reactpress-server start
-```
+## PM2 Support
 
-## CLI Commands
+ReactPress server supports PM2 process management for production deployments:
 
-The package includes a powerful CLI for server management:
-
-### Initialize Project
 ```bash
-# Using npx (recommended)
-npx @fecommunity/reactpress-server init [options]
-
-# Or if installed globally
-reactpress-server init [options]
-
-Options:
-  -p, --port <port>     Server port (default: 3002)
-  --api-prefix <prefix> API prefix (default: /api)
-  --db-host <host>      Database host (default: localhost)
-  --db-port <port>      Database port (default: 3306)
-  --db-name <name>      Database name (default: reactpress)
+# Start with PM2
+npx @fecommunity/reactpress-server --pm2
 ```
 
-### Development Mode
-```bash
-# Using npx
-npx @fecommunity/reactpress-server dev [options]
+PM2 features:
+- Automatic process restart on crash
+- Memory monitoring and alerts
+- Log management with rotation
+- Cluster mode support for horizontal scaling
+- Process monitoring dashboard with health checks
 
-# Or if installed globally
-reactpress-server dev [options]
+## Configuration
 
-Options:
-  -p, --port <port>     Server port (default: 3002)
-  --no-open            Don't open browser automatically
+The installation wizard will create a `.env` file with:
+
+```env
+# Database Configuration (Production)
+DB_HOST=prod-db.cluster-xyz.amazonaws.com
+DB_PORT=3306
+DB_USER=reactpress_user
+DB_PASSWD=secure_password_here
+DB_DATABASE=reactpress_prod
+DB_SSL=true
+
+# Site URLs (Production)
+CLIENT_SITE_URL=https://yourdomain.com
+SERVER_SITE_URL=https://api.yourdomain.com
+
+# Security Settings (Production)
+JWT_SECRET=your-very-secure-jwt-secret-here
+JWT_EXPIRES_IN=24h
+JWT_REFRESH_EXPIRES_IN=7d
+
+# SMTP Configuration (Production)
+SMTP_HOST=email-smtp.us-east-1.amazonaws.com
+SMTP_PORT=587
+SMTP_USER=your_smtp_username
+SMTP_PASS=your_smtp_password
+SMTP_FROM=noreply@yourdomain.com
+
+# Cloud Storage (Optional)
+S3_ACCESS_KEY_ID=your_aws_access_key
+S3_SECRET_ACCESS_KEY=your_aws_secret_key
+S3_BUCKET_NAME=your_bucket_name
+S3_REGION=us-east-1
 ```
 
-### Production Mode
-```bash
-# Using npx
-npx @fecommunity/reactpress-server start [options]
+## API Documentation
 
-# Or if installed globally
-reactpress-server start [options]
+Once running, visit `http://localhost:3002/api` for:
+- Interactive Swagger documentation
+- API endpoint explorer
+- Authentication examples
+- Response schemas
+- Request/response validation
+- Code generation for multiple languages
 
-Options:
-  -p, --port <port>     Server port (default: 3002)
-```
+## Development
 
-### Build Project
 ```bash
-# Using npx
-npx @fecommunity/reactpress-server build
+# Clone repository
+git clone https://github.com/fecommunity/reactpress.git
+cd reactpress/server
 
-# Or if installed globally
-reactpress-server build
-```
+# Install dependencies
+pnpm install
 
-## Environment Configuration
+# Start development server with hot reload
+pnpm run dev
 
-Create a `.env` file in your project root:
+# Start with PM2 (development)
+pnpm run pm2:start
 
-```env
-# Server Configuration
-SERVER_PORT=3002
-SERVER_API_PREFIX=/api
-NODE_ENV=development
+# Build for production
+pnpm run build
 
-# Database Configuration
-DB_HOST=localhost
-DB_PORT=3306
-DB_USERNAME=root
-DB_PASSWORD=your_password
-DB_DATABASE=reactpress
-
-# JWT Configuration
-JWT_SECRET=your_jwt_secret_key
-JWT_EXPIRES_IN=7d
-
-# File Upload (Optional - Ali OSS)
-OSS_ACCESS_KEY_ID=your_access_key_id
-OSS_ACCESS_KEY_SECRET=your_access_key_secret
-OSS_BUCKET=your_bucket_name
-OSS_REGION=your_region
-
-# Email Configuration (Optional)
-EMAIL_HOST=smtp.gmail.com
-EMAIL_PORT=587
-EMAIL_USER=your_email@gmail.com
-EMAIL_PASS=your_app_password
-```
-
-## Programmatic Usage
+# Run tests
+pnpm run test
 
-You can also use the server programmatically in your Node.js applications:
+# Run tests with coverage
+pnpm run test:cov
 
-```typescript
-import { bootstrap } from '@fecommunity/reactpress-server';
-
-async function startServer() {
-  const app = await bootstrap({
-    port: 3002,
-    apiPrefix: '/api',
-    cors: true
-  });
-  
-  console.log('ReactPress server started successfully!');
-}
-
-startServer();
+# Run end-to-end tests
+pnpm run test:e2e
 ```
 
-## API Endpoints
-
-The server provides comprehensive REST APIs:
-
-### Authentication
-- `POST /api/auth/login` - User login
-- `POST /api/auth/register` - User registration
-- `GET /api/auth/profile` - Get user profile
-
-### Articles
-- `GET /api/articles` - Get articles (with pagination)
-- `POST /api/articles` - Create article
-- `GET /api/articles/:id` - Get article by ID
-- `PUT /api/articles/:id` - Update article
-- `DELETE /api/articles/:id` - Delete article
-
-### Categories
-- `GET /api/categories` - Get all categories
-- `POST /api/categories` - Create category
-- `PUT /api/categories/:id` - Update category
-- `DELETE /api/categories/:id` - Delete category
+## Project Structure
 
-### Tags
-- `GET /api/tags` - Get all tags
-- `POST /api/tags` - Create tag
-- `PUT /api/tags/:id` - Update tag
-- `DELETE /api/tags/:id` - Delete tag
+```
+server/
+├── src/
+│   ├── modules/          # Feature modules
+│   │   ├── article/      # Article management
+│   │   ├── auth/         # Authentication
+│   │   ├── user/         # User management
+│   │   └── ...           # Other modules
+│   ├── common/           # Shared utilities and decorators
+│   ├── filters/          # Exception filters
+│   ├── interceptors/     # Request/response interceptors
+│   ├── guards/           # Authentication guards
+│   ├── pipes/            # Data transformation pipes
+│   ├── logger/           # Logging utilities
+│   └── utils/            # Utility functions
+├── public/               # Static assets
+│   └── swagger/          # Swagger documentation
+├── dist/                 # Compiled output
+└── bin/                  # CLI entry points
+```
 
-### Comments
-- `GET /api/comments` - Get comments
-- `POST /api/comments` - Create comment
-- `PUT /api/comments/:id` - Update comment
-- `DELETE /api/comments/:id` - Delete comment
+## Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `DB_HOST` | Database host | `127.0.0.1` |
+| `DB_PORT` | Database port | `3306` |
+| `DB_USER` | Database username | - |
+| `DB_PASSWD` | Database password | - |
+| `DB_DATABASE` | Database name | `reactpress` |
+| `SERVER_PORT` | Server port | `3002` |
+| `JWT_SECRET` | JWT secret key | - |
+| `CLIENT_SITE_URL` | Client site URL | `http://localhost:3001` |
+| `SERVER_SITE_URL` | Server site URL | `http://localhost:3002` |
+| `SMTP_HOST` | SMTP server host | - |
+| `SMTP_PORT` | SMTP server port | - |
+| `SMTP_USER` | SMTP username | - |
+| `SMTP_PASS` | SMTP password | - |
 
-### File Upload
-- `POST /api/upload/image` - Upload image
-- `POST /api/upload/file` - Upload file
+## CLI Commands
 
-## Database Setup
+```bash
+# Show help
+npx @fecommunity/reactpress-server --help
 
-### MySQL Installation
+# Start server
+npx @fecommunity/reactpress-server
 
-**Ubuntu/Debian:**
-```bash
-sudo apt update
-sudo apt install mysql-server
-sudo mysql_secure_installation
-```
+# Start with PM2
+npx @fecommunity/reactpress-server --pm2
 
-**macOS:**
-```bash
-brew install mysql
-brew services start mysql
-```
+# Specify port
+npx @fecommunity/reactpress-server --port 3002
 
-**Windows:**
-Download and install from [MySQL Official Website](https://dev.mysql.com/downloads/mysql/)
+# Enable verbose logging
+npx @fecommunity/reactpress-server --verbose
 
-### Database Creation
+# Run database migrations
+npx @fecommunity/reactpress-server --migrate
 
-```sql
-CREATE DATABASE reactpress;
-CREATE USER 'reactpress'@'localhost' IDENTIFIED BY 'your_password';
-GRANT ALL PRIVILEGES ON reactpress.* TO 'reactpress'@'localhost';
-FLUSH PRIVILEGES;
+# Seed database with sample data
+npx @fecommunity/reactpress-server --seed
 ```
 
-## Advanced Usage
+## Integration with ReactPress Toolkit
 
-### Custom Configuration
+The server automatically generates the OpenAPI specification that powers the ReactPress Toolkit:
 
 ```typescript
-import { NestFactory } from '@nestjs/core';
-import { AppModule } from '@fecommunity/reactpress-server';
-
-async function bootstrap() {
-  const app = await NestFactory.create(AppModule);
-  
-  // Custom middleware
-  app.use('/custom', customMiddleware);
-  
-  // Custom global filters
-  app.useGlobalFilters(new CustomExceptionFilter());
-  
-  await app.listen(3002);
-}
-
-bootstrap();
-```
-
-### Plugin Development
+// The toolkit is automatically generated from this server's API
+import { api, types } from '@fecommunity/reactpress-toolkit';
 
-```typescript
-import { Module } from '@nestjs/common';
-import { PluginInterface } from '@fecommunity/reactpress-server';
-
-@Module({
-  // Your plugin implementation
-})
-export class CustomPlugin implements PluginInterface {
-  install() {
-    // Plugin installation logic
-  }
-}
+// All API endpoints are strongly typed
+const articles: types.IArticle[] = await api.article.findAll();
 ```
 
-## Deployment
-
-### PM2 (Recommended)
+## Database Schema
+
+ReactPress uses MySQL/PostgreSQL with the following key tables:
+- `users` - User accounts and profiles with 2FA support
+- `articles` - Blog posts and content with versioning
+- `categories` - Content categorization with hierarchy
+- `tags` - Content tagging system
+- `comments` - Reader comments and discussions with moderation
+- `files` - Media file management with cloud storage
+- `settings` - System configuration with environment overrides
+- `views` - Analytics and tracking
+- `webhooks` - Event-driven integrations
+- `scheduled_tasks` - Automated operations
+
+## Security Features
+
+- **JWT Authentication** - Secure token-based authentication with refresh rotation
+- **Rate Limiting** - Adaptive throttling to prevent abuse
+- **Input Validation** - Sanitize all user inputs with Zod schema validation
+- **Helmet.js** - Secure HTTP headers
+- **CSRF Protection** - Prevent cross-site request forgery
+- **SQL Injection Prevention** - Through TypeORM parameterized queries
+- **CORS Configuration** - Controlled cross-origin resource sharing
+- **Data Encryption** - At-rest encryption for sensitive data
+- **Audit Logging** - Comprehensive activity tracking
+
+## Performance Optimization
+
+- **Database Indexing** - Optimized queries with proper indexing
+- **Connection Pooling** - Efficient database connection management
+- **Caching** - Redis integration for frequently accessed data
+- **Compression** - Gzip compression for API responses
+- **Pagination** - Efficient data retrieval for large datasets
+- **Query Optimization** - TypeORM query builder for complex operations
+- **Background Jobs** - Queue system for long-running tasks
+
+## Testing
 
 ```bash
-# Install PM2
-npm install -g pm2
+# Run unit tests
+pnpm run test
 
-# Start with PM2
-npm run pm2
-
-# Monitor
-pm2 monitor
-```
-
-### Docker
-
-```dockerfile
-FROM node:18-alpine
-WORKDIR /app
-COPY package*.json ./
-RUN npm install
-COPY . .
-RUN npm run build
-EXPOSE 3002
-CMD ["npm", "start"]
-```
+# Run integration tests
+pnpm run test:integration
 
-### Docker Compose
-
-```yaml
-version: '3.8'
-services:
-  reactpress-server:
-    build: .
-    ports:
-      - "3002:3002"
-    environment:
-      - DB_HOST=mysql
-      - DB_USERNAME=root
-      - DB_PASSWORD=password
-      - DB_DATABASE=reactpress
-    depends_on:
-      - mysql
-  
-  mysql:
-    image: mysql:5.7
-    environment:
-      - MYSQL_ROOT_PASSWORD=password
-      - MYSQL_DATABASE=reactpress
-    ports:
-      - "3306:3306"
-```
+# Run end-to-end tests
+pnpm run test:e2e
 
-## Integration with Frontend
+# Run tests with coverage
+pnpm run test:cov
 
-Use with ReactPress client:
+# Run linting
+pnpm run lint
 
-```bash
-# Install both server and client
-npm install @fecommunity/reactpress-server @fecommunity/reactpress-client @fecommunity/reactpress-config
+# Run formatting
+pnpm run format
 
-# Start server
-npx reactpress-server dev
-
-# In another terminal, start client
-npx reactpress-client dev
+# Run type checking
+pnpm run type-check
 ```
 
-## Troubleshooting
+## Deployment
 
-### Common Issues
+### Production Deployment with PM2
 
-1. **Database Connection Error**
-   ```
-   Error: connect ECONNREFUSED 127.0.0.1:3306
-   ```
-   - Ensure MySQL is running
-   - Check database credentials in `.env`
+```
+# Start server with PM2
+npx @fecommunity/reactpress-server --pm2
 
-2. **Port Already in Use**
-   ```
-   Error: listen EADDRINUSE :::3002
-   ```
-   - Change port in `.env` file or use `-p` option
+# Or build and start manually
+pnpm run build
+pnpm run start:prod
+```
 
-3. **JWT Secret Missing**
-   ```
-   Error: JWT_SECRET is not defined
-   ```
-   - Add `JWT_SECRET=your_secret_key` to `.env`
+## Monitoring & Logging
 
-### Debug Mode
+- **Structured Logging** - JSON-formatted logs for easy parsing
+- **Error Tracking** - Comprehensive error reporting with context
+- **Performance Metrics** - Response time and throughput monitoring
+- **Health Checks** - API endpoint for service status
+- **Alerting** - Integration with monitoring systems (Prometheus, Grafana)
 
-Start server with debug information:
+## Support
 
-```bash
-DEBUG=* npx reactpress-server dev
-```
+- 📖 [Documentation](https://github.com/fecommunity/reactpress)
+- 🐛 [Issues](https://github.com/fecommunity/reactpress/issues)
+- 💬 [Discussions](https://github.com/fecommunity/reactpress/discussions)
+- 📧 [Enterprise Support](mailto:enterprise@reactpress.dev)
 
 ## Contributing
 
-Contributions are welcome! Please feel free to submit a Pull Request.
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/AmazingFeature`)
+3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
+4. Push to the branch (`git push origin feature/AmazingFeature`)
+5. Open a pull request
 
 ## License
 
-MIT
+MIT License - see [LICENSE](LICENSE) file for details.
 
-## Links
+---
 
-- [GitHub Repository](https://github.com/fecommunity/reactpress)
-- [Documentation](https://reactpress.surge.sh)
-- [npm Package](https://www.npmjs.com/package/@fecommunity/reactpress-server)
-- [API Documentation](http://localhost:3002/api) (when server is running)
+Built with ❤️ by [FECommunity](https://github.com/fecommunity)