diff --git a/README_EN.md b/README_EN.md index 8f0f65f..299c24e 100644 --- a/README_EN.md +++ b/README_EN.md @@ -1,98 +1,428 @@ +# Register Manager API +

- Nest Logo + NestJS Logo

-[circleci-image]: https://img.shields.io/circleci/build/github/nestjs/nest/master?token=abc123def456 -[circleci-url]: https://circleci.com/gh/nestjs/nest - -

A progressive Node.js framework for building efficient and scalable server-side applications.

-

-NPM Version -Package License -NPM Downloads -CircleCI -Discord -Backers on Open Collective -Sponsors on Open Collective - Donate us - Support us - Follow us on Twitter +

+ Backend API for managing course registrations and payments +
+ Built with NestJS, Prisma, and PostgreSQL

- -## Description +## πŸ“‹ Description + +Register Manager API is a full-featured backend application for managing course registrations. It provides a complete system for authentication, user management, course management, registrations, and payments. + +### ✨ Key Features + +- πŸ” **Full authentication** with JWT, refresh tokens, and email verification +- πŸ‘₯ **User management** with role-based access control (SUPER_ADMIN, ADMIN, USER) +- πŸ“š **Course management** with detailed course information +- πŸ“ **Registration system** with status tracking +- πŸ’³ **Payment processing** with multi-currency support (USD, EUR, XOF) via FedaPay +- πŸ“§ **Email service** for notifications, verification, and password resets +- πŸ”„ **WhatsApp integration** for communications +- πŸ›‘οΈ **Rate limiting** and advanced security +- πŸ§ͺ **Comprehensive tests** with 100% coverage on core modules + +## πŸ—οΈ Project Architecture + +### Tech Stack + +| Technology | Version | Purpose | +|----------------|----------|--------------------------------| +| **NestJS** | ^11.0.1 | Node.js TypeScript framework | +| **Prisma** | ^6.15.0 | Database ORM | +| **PostgreSQL** | 15 | Relational database | +| **JWT** | ^11.0.0 | Token-based authentication | +| **Bcrypt** | ^6.0.0 | Password hashing | +| **Nodemailer** | ^7.0.6 | Email delivery service | +| **Jest** | ^29.7.0 | Testing framework | +| **Docker** | - | Database containerization | + +### Module Structure + +``` +src/ +β”œβ”€β”€ auth/ # Authentication module +β”‚ β”œβ”€β”€ dto/ # Data transfer objects +β”‚ β”œβ”€β”€ guards/ # Security guards +β”‚ └── services/ # Business logic +β”œβ”€β”€ user/ # User management +β”œβ”€β”€ admin/ # Admin operations +β”œβ”€β”€ course/ # Course management +β”œβ”€β”€ registration/ # Registration system +β”œβ”€β”€ payment/ # Payment processing +β”œβ”€β”€ mail/ # Email service +β”œβ”€β”€ whatsapp/ # WhatsApp integration +β”œβ”€β”€ common/ # Shared utilities, filters, interfaces +└── main.ts # Application entry point +``` + +## πŸš€ Quick Start + +### Prerequisites + +- **Node.js** 18+ ([Download](https://nodejs.org/)) +- **npm** (bundled with Node.js) +- **PostgreSQL** (or Docker for the bundled database) +- **Git** + +### Automated Setup + +```bash +# Clone the repository +git clone https://github.com/Romaric-py/register-manager-api.git +cd register-manager-api + +# Run the initialization script +./init.sh +``` + +The `init.sh` script automates: +- βœ… Prerequisites check +- βœ… Dependency installation +- βœ… Environment configuration +- βœ… Database startup (Docker) +- βœ… Prisma client generation +- βœ… Database migrations +- βœ… Initial data seeding +- βœ… Project build + +### Manual Setup + +```bash +# 1. Install dependencies +npm install + +# 2. Configure environment +cp .env.example .env +# Edit .env with your values + +# 3. Start PostgreSQL (with Docker) +docker-compose up -d manager-db + +# 4. Generate Prisma client +npx prisma generate + +# 5. Apply migrations +npx prisma migrate deploy + +# 6. Seed initial data +npm run seed + +# 7. Build the project +npm run build +``` + +## πŸ”§ Configuration + +### Environment Variables + +Copy `.env.example` to `.env` and configure the values: + +```bash +# Database +DATABASE_URL=postgresql://user:password@localhost:5434/mydb + +# JWT +JWT_SECRET=your-super-secret-jwt-key +JWT_ACCESS_TOKEN_EXPIRY=1800000 # 30 minutes (ms) +JWT_REFRESH_TOKEN_EXPIRY=604800000 # 7 days (ms) + +# Email (SMTP) +MAIL_HOST=smtp.gmail.com +MAIL_USER=your-email@gmail.com +MAIL_PASSWORD=your-app-password + +# Frontend URL (used in email links) +FRONTEND_URL=http://localhost:3001 + +# Super Admin credentials (used during seeding) +SUPER_ADMIN_EMAIL=admin@registerManager.com +SUPER_ADMIN_PASSWORD=AdminPassword123! +``` + +πŸ“– **Full documentation**: See [ENVIRONMENT_VARIABLES.md](./ENVIRONMENT_VARIABLES.md) + +### Database + +#### Option 1: Docker (Recommended) + +```bash +# Start PostgreSQL +docker-compose up -d manager-db + +# Check status +docker-compose ps +``` + +#### Option 2: Local PostgreSQL + +```bash +# Ubuntu/Debian +sudo apt install postgresql postgresql-contrib + +# macOS +brew install postgresql + +# Create database and update DATABASE_URL in .env +createdb mydb +``` + +## πŸƒβ€β™‚οΈ Running the Application -[Nest](https://github.com/nestjs/nest) framework TypeScript starter repository. +```bash +# Development mode (with hot reload) +npm run start:dev + +# Production mode +npm run start:prod + +# Debug mode +npm run start:debug +``` + +The API is available at `http://localhost:3000`. + +## πŸ“‘ API Endpoints + +### Authentication + +| Method | Endpoint | Description | Auth | +|--------|--------------------------------------|---------------------------------|------| +| POST | `/auth/register` | Register a new user | – | +| POST | `/auth/login` | Login | – | +| POST | `/auth/logout` | Logout | JWT | +| POST | `/auth/verify-email` | Verify email address | – | +| POST | `/auth/resend-verification-email` | Resend verification email | – | +| POST | `/auth/request-password-reset` | Request password reset | – | +| POST | `/auth/reset-password` | Reset password with token | – | +| POST | `/auth/create-admin` | Create an admin account | SUPER_ADMIN | + +### Courses + +| Method | Endpoint | Description | Auth | +|--------|----------------------------|--------------------------|------------| +| POST | `/course` | Create a course | SUPER_ADMIN | +| GET | `/course` | List all courses | SUPER_ADMIN | +| GET | `/course/stats` | Course statistics | SUPER_ADMIN | +| GET | `/course/:id` | Get course details | SUPER_ADMIN | +| PATCH | `/course/:id` | Update a course | SUPER_ADMIN | +| PATCH | `/course/:id/toggle-active`| Toggle active status | SUPER_ADMIN | +| DELETE | `/course/:id` | Delete a course | SUPER_ADMIN | + +### Registrations + +| Method | Endpoint | Description | Auth | +|--------|---------------------------------|------------------------------------------|---------| +| POST | `/registration` | Register for a course | JWT | +| POST | `/registration/many-for-one` | Register a user to multiple courses | JWT | +| POST | `/registration/one-for-many` | Register multiple users to one course | JWT | +| GET | `/registration/me` | Current user's registrations | JWT | +| GET | `/registration/all` | All registrations | ADMIN+ | +| GET | `/registration/:id` | Get registration details | JWT | +| PATCH | `/registration/:id` | Update a registration | ADMIN+ | +| DELETE | `/registration/:id` | Cancel a registration | JWT | + +### Payments + +| Method | Endpoint | Description | Auth | +|--------|-------------------------------|------------------------------|------| +| POST | `/payment/generate-link` | Generate a payment link | JWT | +| GET | `/payment/available-amounts` | Get available payment amounts| JWT | +| POST | `/payment/callback` | Payment callback handler | – | -## Project setup +### Default Admin Account + +After running the seed, a super admin account is created: +- **Email**: `admin@registerManager.com` +- **Password**: `AdminPassword123!` + +⚠️ **Change these credentials before going to production!** + +## πŸ§ͺ Testing ```bash -$ npm install +# All unit tests +npm run test + +# Watch mode +npm run test:watch + +# Coverage report +npm run test:cov + +# End-to-end tests +npm run test:e2e + +# Test a specific module +npm test auth +npm test registration ``` -## Compile and run the project +### Current Coverage + +- **Auth module**: 100% coverage +- **Registration module**: Comprehensive unit and integration tests +- **E2E tests**: Coverage for all major endpoints + +## πŸ”’ Security + +- **JWT** access & refresh tokens with configurable expiry +- **Bcrypt** password hashing +- **Rate limiting** (configurable via `THROTTLER_*` env vars) +- **Input validation** with `class-validator` +- **CORS** with configurable allowed origins +- **Role-based guards** for route authorization +- **Prisma exception filters** for safe error handling + +## πŸ“¦ npm Scripts + +| Script | Description | +|-------------------------|-----------------------------------| +| `npm run start` | Start the application | +| `npm run start:dev` | Start in development (watch) mode | +| `npm run start:prod` | Start in production mode | +| `npm run build` | Compile TypeScript | +| `npm run test` | Run unit tests | +| `npm run test:cov` | Run tests with coverage report | +| `npm run test:e2e` | Run end-to-end tests | +| `npm run lint` | Lint and auto-fix code | +| `npm run format` | Format code with Prettier | +| `npm run seed` | Reset database with initial data | + +## 🐳 Docker ```bash -# development -$ npm run start +# Start only the PostgreSQL database +docker-compose up -d manager-db -# watch mode -$ npm run start:dev +# Stop all containers +docker-compose down -# production mode -$ npm run start:prod +# View database logs +docker-compose logs -f manager-db ``` -## Run tests +## πŸ“Š Database + +### Data Models + +- **User** – Email, hashed password, phone, role, email verification, password reset tokens +- **Course** – Title, description, price, duration, dates, location, prerequisites, objectives +- **Registration** – Links users to courses with status (PENDING / CONFIRMED / CANCELLED / COMPLETED) +- **Payment** – Payment records with status (PENDING / COMPLETED / FAILED / REFUNDED), currency (USD / EUR / XOF) +- **RefreshToken** – JWT refresh token storage +- **ContactMessage** – Contact form submissions + +### Prisma Commands ```bash -# unit tests -$ npm run test +# Create a new migration +npx prisma migrate dev --name "description" -# e2e tests -$ npm run test:e2e +# Apply pending migrations +npx prisma migrate deploy -# test coverage -$ npm run test:cov +# Reset the database +npx prisma migrate reset + +# Open Prisma Studio (GUI) +npx prisma studio ``` -## Deployment +## πŸš€ Deployment + +### Production Requirements -When you're ready to deploy your NestJS application to production, there are some key steps you can take to ensure it runs as efficiently as possible. Check out the [deployment documentation](https://docs.nestjs.com/deployment) for more information. +- Node.js 18+ +- PostgreSQL database +- Secure environment variables +- Configured SMTP service +- Domain with HTTPS -If you are looking for a cloud-based platform to deploy your NestJS application, check out [Mau](https://mau.nestjs.com), our official platform for deploying NestJS applications on AWS. Mau makes deployment straightforward and fast, requiring just a few simple steps: +### Production Environment Variables ```bash -$ npm install -g @nestjs/mau -$ mau deploy +NODE_ENV=production +JWT_SECRET=ultra-secure-secret +DATABASE_URL=postgresql://user:password@prod-db:5432/dbname +FRONTEND_URL=https://your-domain.com +MAIL_HOST=your-smtp-server.com ``` -With Mau, you can deploy your application in just a few clicks, allowing you to focus on building features rather than managing infrastructure. +### Deploy Commands + +```bash +# Build +npm run build + +# Start +npm run start:prod -## Resources +# With PM2 (recommended) +pm2 start dist/main.js --name register-manager-api +``` -Check out a few resources that may come in handy when working with NestJS: +## πŸ†˜ Troubleshooting -- Visit the [NestJS Documentation](https://docs.nestjs.com) to learn more about the framework. -- For questions and support, please visit our [Discord channel](https://discord.gg/G7Qnnhy). -- To dive deeper and get more hands-on experience, check out our official video [courses](https://courses.nestjs.com/). -- Deploy your application to AWS with the help of [NestJS Mau](https://mau.nestjs.com) in just a few clicks. -- Visualize your application graph and interact with the NestJS application in real-time using [NestJS Devtools](https://devtools.nestjs.com). -- Need help with your project (part-time to full-time)? Check out our official [enterprise support](https://enterprise.nestjs.com). -- To stay in the loop and get updates, follow us on [X](https://x.com/nestframework) and [LinkedIn](https://linkedin.com/company/nestjs). -- Looking for a job, or have a job to offer? Check out our official [Jobs board](https://jobs.nestjs.com). +### Database connection errors -## Support +```bash +# Check container status +docker-compose ps +docker-compose logs manager-db -Nest is an MIT-licensed open source project. It can grow thanks to the sponsors and support by the amazing backers. If you'd like to join them, please [read more here](https://docs.nestjs.com/support). +# Restart the database +docker-compose down +docker-compose up -d manager-db +``` -## Stay in touch +### Prisma errors -- Author - [Kamil MyΕ›liwiec](https://twitter.com/kammysliwiec) -- Website - [https://nestjs.com](https://nestjs.com/) -- Twitter - [@nestframework](https://twitter.com/nestframework) +```bash +# Regenerate the client +npx prisma generate -## License +# Reapply migrations +npx prisma migrate reset +``` + +### Build errors -Nest is [MIT licensed](https://github.com/nestjs/nest/blob/master/LICENSE). +```bash +# Clean install +rm -rf node_modules package-lock.json +npm install +npm run build +``` + +## 🀝 Contributing + +1. **Fork** the project +2. **Create** a feature branch (`git checkout -b feature/AmazingFeature`) +3. **Commit** your changes (`git commit -m 'Add AmazingFeature'`) +4. **Push** the branch (`git push origin feature/AmazingFeature`) +5. **Open** a Pull Request + +### Code Standards + +- **ESLint**: Strict TypeScript configuration +- **Prettier**: Automatic code formatting +- **Tests**: Coverage required for new code + +## πŸ“„ License + +This project is **UNLICENSED** β€” see [package.json](./package.json) for details. + +## πŸ“ž Contact + +- **Repository**: [https://github.com/Romaric-py/register-manager-api](https://github.com/Romaric-py/register-manager-api) + +--- + +

+ Built with ❀️ and NestJS +