cube-ms/templates/basic/README.md

Production-ready microservice framework with health monitoring, validation, error handling, and Docker Swarm support

# My Cube-MS Application

A production-ready microservice built with Cube-MS framework.

## Features

- ✅ **Production Ready**: Security, rate limiting, monitoring out of the box
- 🔒 **Security**: XSS, SQL injection, NoSQL injection protection
- 📊 **Monitoring**: Real-time performance and health monitoring
- 🐳 **Docker Ready**: Docker Swarm compatible with health checks
- 🚀 **High Performance**: Circuit breakers, connection pooling, graceful shutdown
- 📝 **Structured Logging**: MongoDB integration with log streaming

## Quick Start

### 1. Install Dependencies

```bash
npm install
```

### 2. Environment Setup

```bash
cp .env.example .env
# Edit .env with your configuration
```

### 3. Development

```bash
npm run dev
```

Your service will be running at `http://localhost:3000`

### 4. Production

```bash
npm run build
npm start
```

## Available Commands

```bash
npm run dev      # Start development server with hot reload
npm run build    # Build for production
npm start        # Start production server
npm test         # Run tests
npm run generate # Generate components (service, route, model, etc.)
```

## API Endpoints

### Health Checks
- `GET /health` - Overall health status
- `GET /health/live` - Liveness probe (Kubernetes)
- `GET /health/ready` - Readiness probe (Kubernetes)
- `GET /health/detailed` - Detailed health information

### API Routes
- `GET /` - Welcome message and API documentation
- `GET /api` - API documentation
- `GET /api/status` - Service status
- `POST /api/echo` - Echo endpoint for testing
- `GET /api/hello/:name?` - Hello endpoint with parameters
- `GET /api/protected` - Protected endpoint (requires API key)

## Code Generation

Generate new components using the CLI:

```bash
# Generate a new service
npx cube-ms generate service user

# Generate a new route
npx cube-ms generate route user

# Generate a new model
npx cube-ms generate model user

# Generate a new controller
npx cube-ms generate controller user

# Generate a new middleware
npx cube-ms generate middleware auth
```

## Project Structure

```
src/
├── config/           # Configuration files
│   └── app.config.js # Main application configuration
├── controllers/      # Request controllers
├── services/         # Business logic services
├── models/           # Data models and schemas
├── routes/           # Route definitions
│   ├── index.js      # Route setup
│   ├── api.routes.js # API routes
│   └── health.routes.js # Health check routes
├── middleware/       # Custom middleware
├── utils/            # Utility functions
└── index.js          # Application entry point
```

## Environment Variables

See `.env.example` for all available configuration options.

Key variables:
- `PORT` - Server port (default: 3000)
- `NODE_ENV` - Environment (development/production)
- `MONGODB_URL` - MongoDB connection string
- `SECURITY_LEVEL` - Security level (strict/standard/lenient)
- `RATE_LIMIT_PRESET` - Rate limiting preset (strict/moderate/lenient)

## Docker Deployment

### Development
```bash
docker build -t my-app .
docker run -p 3000:3000 my-app
```

### Production (Docker Swarm)
```bash
docker stack deploy -c docker-compose.yml my-app-stack
```

## Monitoring

The application includes built-in monitoring:
- Memory usage tracking
- CPU usage monitoring  
- Request response times (p50, p95, p99)
- Error rate tracking
- Connection monitoring

Access monitoring data via health endpoints or check logs.

## Security Features

- Rate limiting with sliding window
- Input validation and sanitization
- XSS protection
- SQL/NoSQL injection prevention
- Security headers (Helmet.js)
- Request timeout protection

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

## License

MIT