myex-cli/README.md

Opinionated Express.js framework with CLI tools

# MYX - Opinionated Express.js Framework with CLI

A modern, opinionated Express.js framework with CLI tools for rapid development. Build robust, scalable, and maintainable Node.js applications with best practices baked in.

## Features

- **ES6 Modules**: Modern JavaScript syntax with import/export
- **MongoDB Integration**: Database integration with Mongoose
- **Authentication**: JWT-based authentication with Passport.js
- **Security**: Best practices with Helmet, CORS, and rate limiting
- **Logging**: Comprehensive logging with Winston
- **Process Management**: PM2 for clustering and performance
- **Containerization**: Docker and Kubernetes support
- **Testing**: Jest and Supertest for API testing
- **API Documentation**: Swagger/OpenAPI integration

## Prerequisites

- Node.js (>= 18.0.0)
- MongoDB (>= 6.0)
- Docker and Docker Compose (optional)
- Kubernetes (optional)

## Getting Started

### Installation

#### As a Development Tool

Install MYX CLI globally:

```bash
npm install -g myx-cli
```

This will give you access to the `myx` command for creating and managing MYX applications.

#### Creating a New Project

Create a new MYX project:

```bash
myx new my-project
cd my-project
```

This will scaffold a new MYX application in the `my-project` directory.

Options:
- `--no-git`: Skip git initialization
- `--no-install`: Skip npm install
- `--db <database>`: Choose database (mongodb, postgres, mysql)
- `--auth <auth>`: Choose authentication (jwt, passport, oauth)

### Generating Code

MYX CLI provides several generators to speed up development:

#### Generate a Complete Feature

```bash
myx generate feature user --fields name:String:true email:String:true:null:null password:String:true role:String:false:user:null
```

This will generate:
- Model: `src/models/user.model.js`
- Service: `src/services/user.service.js`
- Controller: `src/controllers/user.controller.js`
- Routes: `src/routes/user.routes.js`

And update routes/index.js to include the new routes.

#### Generate Individual Components

You can also generate components individually:

```bash
# Generate a model
myx generate model product --fields name:String:true price:Number:true category:String:false

# Generate a controller
myx generate controller product --model product

# Generate a service
myx generate service product --model product

# Generate a route
myx generate route product --controller product

# Generate a middleware
myx generate middleware auth
```

### Running the Application

#### Development Mode

```bash
npm run dev
```

This will start the application with Nodemon for automatic restarts on file changes.

#### Production Mode

```bash
npm start
```

#### With PM2

```bash
npm run pm2:start
```

To stop the PM2 processes:

```bash
npm run pm2:stop
```

### Docker Deployment

#### Build and Run with Docker

```bash
npm run docker:build
npm run docker:run
```

#### Using Docker Compose

```bash
docker-compose -f deploy/docker-compose.yml up -d
```

### Kubernetes Deployment

1. Update the Kubernetes manifests in the `deploy/k8s` directory with your configuration.

2. Apply the manifests:
   ```bash
   kubectl apply -f deploy/k8s/
   ```

## Project Structure

```
/myx
├── /src                 # Source code
│   ├── /config          # Environment configurations
│   ├── /controllers     # Request handlers
│   ├── /middlewares     # Custom middleware
│   ├── /models          # MongoDB schemas
│   ├── /routes          # API routes
│   ├── /security        # Security configurations
│   ├── /services        # Business logic
│   ├── /db              # Database connection
│   ├── /utils           # Utility functions
│   └── app.js           # Express app setup
├── /deploy              # Deployment configurations
│   ├── Dockerfile       # Docker configuration
│   ├── docker-compose.yml # Docker Compose config
│   └── /k8s             # Kubernetes manifests
├── /test                # Tests
├── /docs                # Documentation
├── .env                 # Environment variables
├── package.json         # Dependencies and scripts
└── pm2.config.js        # PM2 configuration
```

## API Documentation

API documentation is available via Swagger UI at `/api-docs` when the application is running. The documentation includes:

- Detailed information about all endpoints
- Request and response schemas
- Authentication requirements
- Example requests and responses

You can also access the raw Swagger/OpenAPI specification at `/swagger.json`.

### Main Endpoints

#### Authentication

- `POST /api/auth/register`: Register a new user
- `POST /api/auth/login`: Login a user
- `POST /api/auth/refresh-token`: Refresh access token
- `POST /api/auth/logout`: Logout a user
- `POST /api/auth/forgot-password`: Request password reset
- `POST /api/auth/reset-password`: Reset password

#### User Management

- `GET /api/users/me`: Get current user profile
- `GET /api/users/:id`: Get user by ID
- `PUT /api/users/:id`: Update user
- `DELETE /api/users/:id`: Delete user (admin only)

#### System

- `GET /health`: API health check
- `GET /api`: API information
- `GET /api-docs`: Swagger documentation

## Testing

Run tests with:

```bash
npm test
```

## Documentation

Additional documentation is available in the `/docs` directory:

- [Folder Structure](docs/folder-structure.md)
- [Application Flow](docs/application-flow.md)
- [Product Requirements Document](docs/prd.md)
- [Technology Stack](docs/tech-stack.md)

## License

MIT

## Contributing

1. Fork the repository
2. Create your feature branch: `git checkout -b feature/my-new-feature`
3. Commit your changes: `git commit -am 'Add some feature'`
4. Push to the branch: `git push origin feature/my-new-feature`
5. Submit a pull request