Ecomm Backend: E-commerce Platform API 🛒⚡

✨ Overview

Welcome to Ecomm Backend, a comprehensive REST API designed for managing a modern e-commerce platform. Built with Swift, Vapor framework, and PostgreSQL, this backend service provides a fast, scalable, and efficient foundation for e-commerce applications. It follows modern API design principles with comprehensive JWT authentication, clean architecture, and robust data validation, making it highly maintainable and performant.

🔋 Key Features

• 🔐 JWT Authentication — Secure endpoints using JSON Web Tokens (JWT) with Bearer token support, ensuring that only authenticated users can access protected resources.
• 🏗️ Clean Architecture — Organized into distinct layers (Controllers, Models, DTOs, Migrations) for clear separation of concerns, making the codebase easy to understand, test, and scale.
• � Full CRUD Operations — Comprehensive Create, Read, Update, and Delete functionality for all core entities:
  • Users: Complete user management with secure bcrypt password hashing and JWT-based authentication.
  • Categories: Product categorization with hierarchical organization and image support.
  • Products: Product catalog management with inventory, pricing, and multi-tag support.
  • Tags: Flexible product tagging system with many-to-many relationships.
  • Orders: Complete order lifecycle from creation to fulfillment with automated inventory management.
  • Reviews: Product review system with ratings and user feedback.
• 🛒 Advanced E-commerce Features — Core e-commerce functionality with:
  • Inventory management with stock tracking and validation
  • Automated order processing with status updates
  • Product image upload and management
  • Multi-tag product organization
  • User review and rating system
• 🔍 Flexible Product Search — Search products by category, tags, price range, and availability status.
• 🛡️ Request Validation — Built-in validation using Vapor's validation system with comprehensive error messages for data integrity.
• 🐘 PostgreSQL Integration — Utilizes PostgreSQL with Fluent ORM for reliable relational data storage and complex queries.
• 🚀 High Performance — Built on Vapor framework with SwiftNIO for blazing-fast HTTP performance and async/await support.
• 📊 Interactive Documentation — Auto-generated Swagger/OpenAPI documentation with "Try it out" functionality.
• ⚙️ Centralized Configuration — Manages all environment-specific settings securely through environment variables.
• � Security Middleware — CORS protection, file upload validation, JWT middleware, and comprehensive API security.

🧑‍💻 How It Works

1. User registers by sending their details to the /api/v1/auth/register endpoint with email, password, and personal information.
2. User authenticates via /api/v1/auth/login to receive JWT tokens for accessing protected endpoints.
3. Admin manages catalog by creating categories, products, and tags through protected endpoints.
4. User browses products by category or tag, with detailed product information and reviews.
5. User creates orders by selecting products and quantities, the system checks inventory and creates the order.
6. JWT Middleware validates tokens for protected endpoints and extracts user information for authorization.
7. The system follows MVC pattern: Models define data structure, Controllers handle business logic, DTOs manage data transfer.
8. PostgreSQL stores all data with proper relationships, constraints, and indexes for data integrity.
9. Structured JSON responses with consistent error handling are returned to the client.

⚙️ Tech Stack

• 🦉 Swift 6 (Programming Language)
• ⚡ Vapor 4 (High-performance Web Framework)
• 🐘 PostgreSQL 16 (Relational Database)
• 🔗 Fluent ORM (Object-Relational Mapping)
• 🔐 JWT (JSON Web Token Authentication)
• 🛡️ Bcrypt (Password Hashing)
• ✅ Vapor Validation (Data Validation)
• 📝 Swagger/OpenAPI (API Documentation)
• 🔄 Environment Variables (Configuration Management)
• 🌐 CORS Middleware (Cross-Origin Resource Sharing)
• 📊 SwiftNIO (Non-blocking I/O Framework)
• 🐳 Docker (Containerization)

📚 Ecomm Backend Resources

• 🌐 Swift Backend: View Code
• 📖 API Documentation: http://localhost:8080/swagger (when running locally)
• 📋 OpenAPI Spec: http://localhost:8080/openapi.json (JSON specification)

🚀 Getting Started

Follow these steps to get Ecomm Backend up and running on your local machine.

Prerequisites

• Swift (version 6.0 or higher)
• PostgreSQL (version 16 or higher)
• Docker (Optional but recommended)
• A tool to interact with your database (e.g., pgAdmin, DBeaver, or psql)

Installation & Setup

1. Clone the repository:

   git clone https://github.com/LouisFernando1204/ecomm-backend.git
   cd ecomm-backend

2. Install Swift dependencies:

   swift package resolve

3. Set up environment variables:

   # Copy the example environment file
   cp .env.example .env
   
   # Edit .env file with your specific configuration
   nano .env  # or use your preferred editor

   Important: Update the following values in your .env file:

   • JWT_SECRET: Use a strong, unique secret key (at least 32 characters)
   • DATABASE_PASSWORD: Set a secure password for your database
   • Other configuration values as needed for your environment

4. Set up the database using Docker (Recommended):

   # Start PostgreSQL with Docker Compose
   docker compose up -d db
   
   # Or start all services including the app
   docker compose up --build

5. Alternative: Manual PostgreSQL Setup:

   # Create database (if not using Docker)
   createdb ecommerce_db
   
   # Set up user and permissions (use the credentials from your .env file)
   psql -d ecommerce_db -c "CREATE USER vapor_username WITH PASSWORD 'vapor_password';"
   psql -d ecommerce_db -c "GRANT ALL PRIVILEGES ON DATABASE ecommerce_db TO vapor_username;"

6. Run database migrations:

   # Using Docker
   docker compose run migrate
   
   # Or manually
   swift run App migrate

7. Build and run the application:

   # Development mode
   swift run App serve
   
   # Or using Docker
   docker compose up app

   The server should now be running on http://localhost:8080.

8. Access API Documentation:

   • Swagger UI: http://localhost:8080/swagger
   • OpenAPI JSON: http://localhost:8080/openapi.json
   • Health Check: http://localhost:8080/health

📋 API Endpoints

Authentication

• POST /api/v1/auth/register - Register new user with email, password, and personal details
• POST /api/v1/auth/login - User login with email and password
• GET /api/v1/auth/me - Get current user profile (protected)
• POST /api/v1/auth/logout - User logout (protected)

User Management

• GET /api/v1/users - Get all users (protected)
• POST /api/v1/users - Create new user (alternative to register)
• GET /api/v1/users/{id} - Get user by ID (protected)
• PUT /api/v1/users/{id} - Update user profile (protected)
• DELETE /api/v1/users/{id} - Delete user account (protected)
• GET /api/v1/users/{id}/orders - Get user's order history (protected)
• GET /api/v1/users/{id}/reviews - Get user's reviews (protected)

Category Management

• GET /api/v1/categories - Get all categories (public)
• GET /api/v1/categories/{id} - Get category by ID (public)
• GET /api/v1/categories/{id}/products - Get products in category (public)
• POST /api/v1/categories - Create new category (admin only)
• PUT /api/v1/categories/{id} - Update category (admin only)
• DELETE /api/v1/categories/{id} - Delete category (admin only)

Product Management

• GET /api/v1/products - Get all products with category and tags (public)
• GET /api/v1/products/{id} - Get product details with category and tags (public)
• GET /api/v1/products/{id}/reviews - Get all reviews for specific product (public)
• POST /api/v1/products - Create new product (protected)
• POST /api/v1/products/with-image - Create product with image upload (protected)
• POST /api/v1/products/upload-image - Upload single product image (protected)
• PUT /api/v1/products/{id} - Update product information (protected)
• DELETE /api/v1/products/{id} - Delete product (protected)
• POST /api/v1/products/{id}/tags/{tagId} - Add tag to product (protected)
• DELETE /api/v1/products/{id}/tags/{tagId} - Remove tag from product (protected)
• POST /api/v1/products/{id}/upload-image - Upload image for specific product (protected)

Tag Management

• GET /api/v1/tags - Get all tags (public)
• GET /api/v1/tags/{id} - Get tag by ID (public)
• GET /api/v1/tags/{id}/products - Get products with specific tag (public)
• POST /api/v1/tags - Create new tag (admin only)
• PUT /api/v1/tags/{id} - Update tag (admin only)
• DELETE /api/v1/tags/{id} - Delete tag (admin only)

Review Management (Protected)

• GET /api/v1/reviews - Get all reviews with user and product info (public)
• GET /api/v1/reviews/{id} - Get review details (public)
• POST /api/v1/reviews - Create new product review (protected)
• PUT /api/v1/reviews/{id} - Update own review (protected)
• DELETE /api/v1/reviews/{id} - Delete own review (protected)

Order Management (Protected)

• GET /api/v1/orders - Get all orders with user and items (protected)
• GET /api/v1/orders/{id} - Get order details with user and order items (protected)
• POST /api/v1/orders - Create new order with inventory validation (protected)
• PUT /api/v1/orders/{id} - Update order status and information (protected)
• DELETE /api/v1/orders/{id} - Cancel/delete order if status is pending (protected)
• GET /api/v1/orders/{id}/items - Get all items in specific order (protected)

🤝 Contributor

• 🧑‍💻 Louis Fernando : @LouisFernando1204