A production-ready NestJS backend API for the Flexify portfolio platform, featuring authentication, content management, and comprehensive REST APIs.
- Overview
- Tech Stack
- Project Structure
- Getting Started
- Architecture
- Modules
- API Documentation
- Development
This backend provides a complete REST API for managing portfolio content, user authentication, and administrative operations. Built with NestJS following best practices for scalability, maintainability, and security.
- Framework: NestJS 11
- Language: TypeScript
- Database: Supabase (PostgreSQL)
- Authentication: JWT (Passport.js)
- Email: Nodemailer with Handlebars templates
- File Upload: Multer
- Validation: class-validator, class-transformer
- Security: Helmet, CORS, Rate Limiting (Throttler)
- Internationalization: Custom i18n implementation
server/
├── src/
│ ├── main.ts # Application entry point
│ │ # - Configures middleware (Helmet, CORS, cookie-parser)
│ │ # - Sets up global pipes, filters, interceptors
│ │ # - Starts the NestJS application
│ │
│ ├── app.module.ts # Root module
│ │ # - Imports all feature modules
│ │ # - Configures global modules (Config, Throttler)
│ │
│ ├── config/ # Configuration
│ │ ├── env.validation.ts # Environment variable validation schema
│ │ └── mailer.config.ts # Email service configuration
│ │
│ ├── constants/ # Application constants
│ │ └── auth.constants.ts # Authentication-related constants
│ │
│ ├── core/ # Core utilities and services
│ │ ├── filters/ # Exception filters
│ │ │ └── http-exception.filter.ts
│ │ │ # - Global exception handler
│ │ │ # - Formats error responses
│ │ │ # - Handles i18n error messages
│ │ │
│ │ ├── interceptors/ # Response interceptors
│ │ │ └── transform.interceptor.ts
│ │ │ # - Transforms responses to consistent format
│ │ │ # - Wraps data in IApiResponse structure
│ │ │
│ │ ├── lib/ # Core libraries
│ │ │ └── supabase/ # Supabase integration
│ │ │ └── supabase.service.ts
│ │ │ # - Database client initialization
│ │ │ # - Storage operations
│ │ │
│ │ ├── services/ # Base services
│ │ │ └── base.service.ts # Base service with common CRUD operations
│ │ │
│ │ └── utils/ # Utility functions
│ │ ├── request.util.ts # Request helper utilities
│ │ ├── response.ts # Response formatting utilities
│ │ └── translations.ts # i18n translation utilities
│ │
│ ├── i18n/ # Internationalization
│ │ ├── en.json # English translations
│ │ └── ar.json # Arabic translations
│ │
│ └── modules/ # Feature modules (NestJS modules)
│ ├── auth/ # Authentication module
│ │ ├── auth.controller.ts # Auth endpoints (login, register, etc.)
│ │ ├── auth.service.ts # Authentication business logic
│ │ ├── auth.module.ts # Module definition
│ │ ├── dto/ # Data Transfer Objects
│ │ │ ├── login.dto.ts
│ │ │ ├── register.dto.ts
│ │ │ ├── refresh-token.dto.ts
│ │ │ ├── verify-email.dto.ts
│ │ │ ├── forgot-password.dto.ts
│ │ │ ├── reset-password.dto.ts
│ │ │ ├── change-password.dto.ts
│ │ │ └── resend-verification.dto.ts
│ │ ├── guards/ # Auth guards
│ │ │ └── jwt-auth.guard.ts
│ │ │ # - Protects routes with JWT validation
│ │ ├── strategies/ # Passport strategies
│ │ │ └── jwt.strategy.ts
│ │ │ # - JWT token validation strategy
│ │ └── types/ # TypeScript types
│ │ └── auth.types.ts
│ │
│ ├── users/ # User management module
│ │ ├── users.controller.ts
│ │ ├── users.service.ts
│ │ ├── users.module.ts
│ │ ├── dto/
│ │ │ ├── create-user.dto.ts
│ │ │ ├── update-user.dto.ts
│ │ │ └── query-user.dto.ts
│ │ ├── enums/
│ │ │ └── user-role.enum.ts
│ │ └── types/
│ │ └── user.types.ts
│ │
│ ├── projects/ # Projects management module
│ │ ├── projects.controller.ts
│ │ ├── projects.service.ts
│ │ ├── projects.module.ts
│ │ ├── dto/
│ │ │ ├── create-project.dto.ts
│ │ │ ├── update-project.dto.ts
│ │ │ ├── query-project.dto.ts
│ │ │ ├── upload-image.dto.ts
│ │ │ ├── create-comment.dto.ts
│ │ │ ├── query-comment.dto.ts
│ │ │ └── create-interaction.dto.ts
│ │ ├── enums/
│ │ │ ├── project-status.enum.ts
│ │ │ ├── project-type.enum.ts
│ │ │ ├── link-type.enum.ts
│ │ │ └── interaction-type.enum.ts
│ │ └── types/
│ │ └── project.types.ts
│ │
│ ├── services/ # Services management module
│ │ ├── services.controller.ts
│ │ ├── services.service.ts
│ │ ├── services.module.ts
│ │ ├── dto/
│ │ │ ├── create-service.dto.ts
│ │ │ ├── update-service.dto.ts
│ │ │ └── query-service.dto.ts
│ │ └── types/
│ │ └── service.types.ts
│ │
│ ├── categories/ # Categories management module
│ │ ├── categories.controller.ts
│ │ ├── categories.service.ts
│ │ ├── categories.module.ts
│ │ └── dto/
│ │ ├── create-category.dto.ts
│ │ └── update-category.dto.ts
│ │
│ ├── technologies/ # Technologies management module
│ │ ├── technologies.controller.ts
│ │ ├── technologies.service.ts
│ │ ├── technologies.module.ts
│ │ └── dto/
│ │ ├── create-technology.dto.ts
│ │ └── update-technology.dto.ts
│ │
│ ├── testimonials/ # Testimonials management module
│ │ ├── testimonials.controller.ts
│ │ ├── testimonials.service.ts
│ │ ├── testimonials.module.ts
│ │ ├── dto/
│ │ │ ├── create-testimonial.dto.ts
│ │ │ ├── update-testimonial.dto.ts
│ │ │ └── query-testimonial.dto.ts
│ │ └── types/
│ │ └── testimonial.types.ts
│ │
│ ├── contacts/ # Contact inquiries module
│ │ ├── contacts.controller.ts
│ │ ├── contacts.service.ts
│ │ ├── contacts.module.ts
│ │ ├── dto/
│ │ │ ├── create-contact.dto.ts
│ │ │ ├── update-contact.dto.ts
│ │ │ ├── query-contact.dto.ts
│ │ │ └── reply-contact.dto.ts
│ │ ├── enums/
│ │ │ └── contact-status.enum.ts
│ │ └── types/
│ │ └── contact.types.ts
│ │
│ ├── inquiry-types/ # Inquiry type management module
│ │ ├── inquiry-types.controller.ts
│ │ ├── inquiry-types.service.ts
│ │ ├── inquiry-types.module.ts
│ │ ├── dto/
│ │ │ ├── create-inquiry-type.dto.ts
│ │ │ ├── update-inquiry-type.dto.ts
│ │ │ └── query-inquiry-type.dto.ts
│ │ └── types/
│ │ └── inquiry-type.types.ts
│ │
│ ├── site-settings/ # Site configuration module
│ │ ├── site-settings.controller.ts
│ │ ├── site-settings.service.ts
│ │ ├── site-settings.module.ts
│ │ ├── dto/
│ │ │ └── update-site-setting.dto.ts
│ │ └── types/
│ │ └── site-settings.types.ts
│ │
│ └── mailer/ # Email service module
│ ├── mailer.module.ts
│ ├── mailer.service.ts
│ └── templates/ # Handlebars email templates
│ ├── welcome.hbs
│ ├── verify-account.hbs
│ ├── password-reset.hbs
│ ├── password-reset-confirmation.hbs
│ └── contact-reply.hbs
│
├── supabase/
│ └── migrations/ # Database migrations
│ ├── 001_create_users_table.sql
│ ├── 002_enable_rls_policies.sql
│ ├── 003_create_avatars_storage.sql
│ ├── 004_create_projects_tables.sql
│ ├── 005_create_inquiry_types_contacts_testimonials_services.sql
│ ├── 006_update_categories_table.sql
│ ├── 007_update_technologies_table.sql
│ ├── 008_remove_color_from_services_inquiry_types.sql
│ ├── 009_create_site_settings.sql
│ ├── 010_add_cv_storage.sql
│ └── 011_verify_site_settings.sql
│
├── test/ # E2E tests
│ ├── app.e2e-spec.ts
│ └── jest-e2e.json
│
├── scripts/ # Utility scripts
│ └── generate-hash.js # Password hash generator
│
├── dist/ # Compiled JavaScript (generated)
├── nest-cli.json # NestJS CLI configuration
├── tsconfig.json # TypeScript configuration
├── tsconfig.build.json # Build TypeScript configuration
└── package.json
Each feature module follows NestJS best practices:
module-name/
├── module-name.controller.ts # REST API endpoints
│ # - Defines routes and HTTP methods
│ # - Uses DTOs for request validation
│ # - Returns responses via service
│
├── module-name.service.ts # Business logic
│ # - Contains all business rules
│ # - Interacts with database via Supabase
│ # - Handles data transformation
│
├── module-name.module.ts # Module definition
│ # - Declares controllers and providers
│ # - Imports required modules
│ # - Exports services for other modules
│
├── dto/ # Data Transfer Objects
│ ├── create-module-name.dto.ts # Validation for create operations
│ ├── update-module-name.dto.ts # Validation for update operations
│ └── query-module-name.dto.ts # Validation for query parameters
│
├── types/ # TypeScript type definitions
│ └── module-name.types.ts # Shared types for the module
│
└── enums/ # Enumerations (if needed)
└── module-name-status.enum.ts
- Request → Controller receives HTTP request
- Validation → DTO validation via class-validator
- Guard → JWT authentication guard (if protected route)
- Service → Business logic execution
- Database → Supabase query execution
- Interceptor → Response transformation
- Response → Formatted JSON response
All API responses follow a consistent structure:
interface IApiResponse<T> {
success: boolean;
message: string;
data: T;
errors?: string[];
}- Node.js 18+ and npm
- Supabase account and project
- Email service credentials (SMTP)
-
Install dependencies
npm install
-
Set up environment variables
Create a
.envfile in the root directory:# Database SUPABASE_URL=your_supabase_url SUPABASE_KEY=your_supabase_key SUPABASE_SERVICE_KEY=your_supabase_service_key # JWT JWT_SECRET=your_jwt_secret JWT_EXPIRES_IN=15m JWT_REFRESH_SECRET=your_refresh_secret JWT_REFRESH_EXPIRES_IN=7d # Server PORT=3000 NODE_ENV=development CORS_ORIGINS=http://localhost:3001 # Email MAILER_HOST=smtp.example.com MAILER_PORT=587 MAILER_USER=your_email@example.com MAILER_PASS=your_password MAILER_FROM=noreply@example.com # Rate Limiting THROTTLE_TTL=60000 THROTTLE_LIMIT=10
-
Run database migrations
Apply migrations from
supabase/migrations/to your Supabase project. -
Start development server
npm run start:dev
The API will be available at
http://localhost:3000/api
Handles user authentication and authorization:
- User registration with email verification
- Login with JWT token generation
- Password reset flow
- Token refresh mechanism
- Email verification
Endpoints:
POST /api/auth/register- Register new userPOST /api/auth/login- User loginPOST /api/auth/refresh- Refresh access tokenPOST /api/auth/verify-email- Verify email addressPOST /api/auth/forgot-password- Request password resetPOST /api/auth/reset-password- Reset passwordPOST /api/auth/change-password- Change password (authenticated)POST /api/auth/resend-verification- Resend verification email
Manages user accounts and profiles:
- CRUD operations for users
- Role-based access control
- User profile management
Endpoints:
GET /api/users- List users (with pagination, filtering)GET /api/users/:id- Get user by IDPOST /api/users- Create user (admin only)PATCH /api/users/:id- Update userDELETE /api/users/:id- Delete user
Manages portfolio projects:
- Create, read, update, delete projects
- Image gallery management
- Project links (GitHub, Live Demo, etc.)
- Comments and interactions
- Project status and type management
Endpoints:
GET /api/projects- List projectsGET /api/projects/:id- Get project detailsPOST /api/projects- Create projectPATCH /api/projects/:id- Update projectDELETE /api/projects/:id- Delete projectPOST /api/projects/:id/images- Upload project imagesPOST /api/projects/:id/comments- Add commentPOST /api/projects/:id/interactions- Add interaction (like/view)
Manages portfolio services:
- Service CRUD operations
- Service icons and descriptions
- Multi-language support
Endpoints:
GET /api/services- List servicesGET /api/services/:id- Get service detailsPOST /api/services- Create servicePATCH /api/services/:id- Update serviceDELETE /api/services/:id- Delete service
Manages project categories:
- Category CRUD operations
- Category organization
Endpoints:
GET /api/categories- List categoriesGET /api/categories/:id- Get categoryPOST /api/categories- Create categoryPATCH /api/categories/:id- Update categoryDELETE /api/categories/:id- Delete category
Manages technology stack:
- Technology CRUD operations
- Technology icons and information
Endpoints:
GET /api/technologies- List technologiesGET /api/technologies/:id- Get technologyPOST /api/technologies- Create technologyPATCH /api/technologies/:id- Update technologyDELETE /api/technologies/:id- Delete technology
Manages client testimonials:
- Testimonial CRUD operations
- Avatar management
- Testimonial approval workflow
Endpoints:
GET /api/testimonials- List testimonialsGET /api/testimonials/:id- Get testimonialPOST /api/testimonials- Create testimonialPATCH /api/testimonials/:id- Update testimonialDELETE /api/testimonials/:id- Delete testimonial
Manages contact inquiries:
- Contact form submissions
- Inquiry status tracking
- Reply functionality
- Email notifications
Endpoints:
GET /api/contacts- List contacts (with filtering)GET /api/contacts/:id- Get contact detailsPOST /api/contacts- Create contact inquiryPATCH /api/contacts/:id- Update contact statusPOST /api/contacts/:id/reply- Reply to contact
Manages inquiry type categories:
- Inquiry type CRUD operations
- Used for categorizing contact inquiries
Endpoints:
GET /api/inquiry-types- List inquiry typesGET /api/inquiry-types/:id- Get inquiry typePOST /api/inquiry-types- Create inquiry typePATCH /api/inquiry-types/:id- Update inquiry typeDELETE /api/inquiry-types/:id- Delete inquiry type
Manages site-wide configuration:
- Hero section settings
- About section content
- Statistics configuration
- Footer settings
- Social media links
- CV file management
Endpoints:
GET /api/site-settings- Get all settingsGET /api/site-settings/:key- Get specific settingPATCH /api/site-settings/:key- Update setting
npm run start:dev # Start development server with hot reload
npm run build # Build for production
npm run start:prod # Start production server
npm run test # Run unit tests
npm run test:e2e # Run E2E tests
npm run lint # Lint code
npm run format # Format code with Prettier- Validation: Use class-validator decorators in DTOs
- Types: Define types in
types/directory - Error Handling: Use custom exceptions with i18n messages
- Response Format: Always use the TransformInterceptor format
- Naming: Follow NestJS conventions (kebab-case for files)
-
Generate module structure:
nest g module modules/your-module nest g controller modules/your-module nest g service modules/your-module
-
Create DTOs in
dto/directory -
Define types in
types/directory -
Implement business logic in service
-
Add routes in controller
-
Import module in
app.module.ts
- JWT Authentication: Secure token-based authentication
- Password Hashing: bcryptjs for password security
- Rate Limiting: Throttler protection against abuse
- CORS: Configurable cross-origin resource sharing
- Helmet: HTTP security headers
- Input Validation: Comprehensive DTO validation
- SQL Injection Protection: Parameterized queries via Supabase
This project is private and proprietary.
Built with ❤️ using NestJS