🌟 AUREA Backend API

Professional Portfolio Management Platform

A comprehensive, production-ready portfolio management system with 65+ API endpoints, dynamic template system, AI-powered PDF processing, and enterprise-grade security.

Features • Quick Start • API Docs • Architecture • Contributing

---

📋 Table of Contents

• Overview
• Key Features
• Technology Stack
• Quick Start
• API Reference
• Architecture
• Testing
• Contributing
• License

---

🎯 Overview

AUREA Backend is a sophisticated portfolio management platform that enables designers, developers, and creative professionals to build, manage, and deploy stunning portfolio websites. Built with modern technologies and best practices, it offers a complete ecosystem for portfolio creation and management.

What Makes AUREA Special?

• 🎨 Dynamic Template System - Schema-driven templates with no-code deployment
• 🤖 AI-Powered Processing - Gemini AI integration for intelligent PDF extraction
• 🌐 Multi-Deployment Options - Vercel deployment or local subdomain hosting
• 📱 Responsive HTML Generation - Automatic mobile-optimized site generation
• 🔒 Enterprise Security - JWT authentication, rate limiting, and role-based access
• ⚡ High Performance - Redis caching, database indexing, and optimized queries
• 📊 Analytics & Tracking - View counts, usage statistics, and user insights

---

✨ Key Features

🔐 Authentication & User Management

• JWT-Based Authentication with secure token management
• Complete User CRUD with profile management and password updates
• Role-Based Access Control (User, Admin, Premium)
• Account Security with password hashing (bcrypt) and validation

📁 Portfolio Management

• Full Portfolio Lifecycle - Create, Read, Update, Delete operations
• Dynamic Template System - 10+ professional templates with schema validation
• Custom Slug URLs - SEO-friendly portfolio URLs
• Publishing System - Publish/unpublish with version control
• View Analytics - Track portfolio views and engagement

� Template System (NEW)

• Schema-Driven Architecture - JSON schema defines form structure
• Real-Time Validation - Content validation against template schema
• Version Control - Template versioning with rollback capability
• Rating System - User-driven template ratings and feedback
• Premium Templates - Support for free and premium template tiers
• 14 Template Endpoints - Complete template lifecycle management

📖 Case Study System

• Structured Project Documentation - Rich case study creation
• Smart Content Transformation - Automatic HTML generation from data
• Linked to Portfolios - Seamless integration with portfolio projects
• Public Access - Share case studies via public URLs
• Responsive Design - Mobile-optimized case study pages

🌐 Site Publishing System

• Vercel Deployment - One-click deployment to Vercel
• Gmail-Style Subdomains ⭐ - Custom subdomains (e.g., aurea.tool/your-name)
• Dual Publishing Modes - Vercel OR local subdomain hosting
• Automatic HTML Generation - Dynamic responsive HTML from portfolio data
• View Tracking - Analytics for published sites

📄 PDF Export System

• Portfolio PDF Export - Generate professional PDF portfolios
• Complete Export - Include all case studies in single PDF
• Template-Based Generation - Multiple PDF templates available
• Download or View - Inline viewing or force download
• Automatic Cleanup - Old PDF cleanup functionality

🤖 AI-Powered PDF Processing

• Gemini AI Integration - Advanced document analysis
• Two-Step Extraction - Complete analysis + pricing focus
• Structured Data Output - Clean, usable JSON format
• Extraction History - Track all processed documents
• Test Endpoints - Verify AI connectivity

🖼️ Media Management

• Cloudinary Integration - Professional image hosting
• Single & Batch Upload - Upload one or multiple images
• Image Validation - Format and size validation
• Automatic Optimization - Image optimization on upload
• Delete Functionality - Remove images from cloud storage

�️ Security & Performance

• Helmet.js - HTTP security headers
• CORS Protection - Configurable cross-origin policies
• Rate Limiting - Per-endpoint rate limits
• Redis Caching - Optional high-performance caching
• Input Validation - Comprehensive request validation
• Error Handling - Centralized error management
• Request Logging - Detailed API request logs

� Interactive Documentation

• Swagger UI - Complete API documentation at /api-docs
• Live Testing - Test endpoints directly from browser
• Request/Response Examples - Comprehensive examples for all endpoints
• Authentication Support - Test protected endpoints with JWT tokens

---

� Technology Stack

Core Technologies

• Runtime: Node.js 18+
• Framework: Express 5.1.0
• Database: MongoDB 8.18+ (Mongoose ODM)
• Authentication: JWT (JSON Web Tokens)
• File Storage: Cloudinary
• Caching: Redis 4.7+ (optional)

Key Dependencies

{
  "express": "^5.1.0",           // Web framework
  "mongoose": "^8.18.1",         // MongoDB ODM
  "jsonwebtoken": "^9.0.2",      // JWT authentication
  "bcrypt": "^6.0.0",            // Password hashing
  "cloudinary": "^2.7.0",        // Media management
  "puppeteer": "^24.25.0",       // PDF generation
  "@google/genai": "^1.21.0",    // AI processing
  "helmet": "^8.0.0",            // Security headers
  "express-rate-limit": "^7.4.0", // Rate limiting
  "swagger-ui-express": "^5.0.1", // API documentation
  "joi": "^17.13.3",             // Validation
  "redis": "^4.7.0"              // Caching
}

Development Tools

• ES6 Modules - Modern JavaScript module system
• Nodemon - Auto-restart on file changes
• Swagger - Interactive API documentation
• dotenv - Environment variable management

---

🚀 Quick Start

Prerequisites

Before you begin, ensure you have the following installed and configured:

• ✅ Node.js 18+ - Download
• ✅ MongoDB - Local instance or MongoDB Atlas account
• ✅ Cloudinary Account - Sign up for image storage
• ✅ Redis (Optional) - Download for caching
• ✅ Git - For version control

Installation

1. Clone the Repository

   git clone https://github.com/your-org/aurea-backend.git
   cd aurea-backend

2. Install Dependencies

   npm install

3. Environment Configuration

   Create a .env file in the root directory:

   cp .env.example .env

   Update the .env file with your configuration:

   # MongoDB Configuration
   MONGODB_URI=mongodb+srv://username:[email protected]/aurea
   
   # JWT Configuration
   JWT_SECRET=your-super-secret-jwt-key-here
   JWT_EXPIRE=30d
   
   # Server Configuration
   PORT=5000
   NODE_ENV=development
   
   # Frontend URL (for CORS)
   FRONTEND_URL=http://localhost:5173
   
   # Cloudinary Configuration
   CLOUDINARY_CLOUD_NAME=your-cloud-name
   CLOUDINARY_API_KEY=your-api-key
   CLOUDINARY_API_SECRET=your-api-secret
   
   # Redis Configuration (Optional - gracefully degrades if unavailable)
   REDIS_URL=redis://localhost:6379
   
   # Google Gemini AI (Optional - for PDF extraction)
   GEMINI_API_KEY=your-gemini-api-key
   
   # Vercel Configuration (Optional - for Vercel deployments)
   VERCEL_TOKEN=your-vercel-token
   VERCEL_ORG_ID=your-org-id
   VERCEL_PROJECT_ID=your-project-id

4. Seed Initial Data (Optional)

   # Seed template data
   node seeds/templateSeeds.js
   
   # Migrate existing portfolios (if upgrading)
   node seeds/migratePortfolios.js

5. Start Development Server

   npm run dev

   Expected Output:

   🚀 AUREA Backend Server
   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
   📊 Environment: development
   🌐 Port: 5000
   ✅ MongoDB Connected: aurea-cluster.mongodb.net
   ✅ Redis Connected: localhost:6379 (optional)
   ✅ Cloudinary Configured: your-cloud-name
   📝 Templates Initialized: 3 templates loaded
   🎯 65+ API Endpoints Active
   📚 API Documentation: http://localhost:5000/api-docs
   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
   ✨ Server ready at: http://localhost:5000
   

6. Verify Installation

   # Test health endpoint
   curl http://localhost:5000/health
   
   # Expected response:
   # {"status":"healthy","timestamp":"2025-10-20T...","database":"connected"}

7. Access API Documentation

   Open your browser and navigate to:

   http://localhost:5000/api-docs
   

Quick Test

Test the API with these commands:

# 1. Register a new user
curl -X POST http://localhost:5000/api/auth/signup \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Doe",
    "email": "[email protected]",
    "password": "SecurePass123!"
  }'

# 2. Login and get JWT token
curl -X POST http://localhost:5000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "SecurePass123!"
  }'

# 3. Get templates (no auth required)
curl http://localhost:5000/api/templates

# 4. Get user profile (auth required - use token from login)
curl http://localhost:5000/api/auth/me \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

---

📚 API Reference

API Endpoints Overview

AUREA Backend provides 65+ RESTful API endpoints organized into 9 main categories:

Category	Endpoints	Description
🏥 Health	1	Server health and status checks
🔐 Authentication	4	User signup, login, profile management
👤 User Management	13	Complete user CRUD operations
📁 Portfolio	9	Portfolio lifecycle management
🎨 Templates	14	Dynamic template system
📖 Case Studies	6	Project case study management
🌐 Site Publishing	10	Vercel & subdomain deployment
📄 PDF Export	5	Portfolio PDF generation
🖼️ Media Upload	2	Image upload and management
🤖 AI Processing	3	PDF extraction with Gemini AI

Quick Reference

Health Check

GET /health

Returns server status, database connectivity, and system info.

---

Authentication Endpoints

POST   /api/auth/signup          # Register new user
POST   /api/auth/login           # Login and get JWT token
GET    /api/auth/me              # Get current user profile (protected)
PUT    /api/auth/me              # Update current user (protected)

Example: User Registration

curl -X POST http://localhost:5000/api/auth/signup \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Jane Designer",
    "email": "[email protected]",
    "password": "SecurePass123!"
  }'

Response:

{
  "success": true,
  "message": "User registered successfully",
  "data": {
    "user": {
      "_id": "6501234567890abcdef12345",
      "name": "Jane Designer",
      "email": "[email protected]",
      "role": "user"
    },
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}

---

User Management Endpoints

GET    /api/users/profile                    # Get current user profile
PUT    /api/users/profile                    # Update profile (name, email, password)
PATCH  /api/users/profile/password           # Change password
POST   /api/users/profile/verify-password    # Verify current password
DELETE /api/users/profile                    # Delete account
GET    /api/users/premium/status             # Check premium status

# Admin endpoints
GET    /api/users                            # List all users (paginated)
GET    /api/users/:id                        # Get user by ID
PUT    /api/users/:id                        # Update user
DELETE /api/users/:id                        # Delete user
GET    /api/users/:id/portfolios             # Get user's portfolios
PUT    /api/users/:id/role                   # Update user role
DELETE /api/users/:id/force                  # Force delete with portfolios

---

Portfolio Endpoints

POST   /api/portfolios                       # Create new portfolio
GET    /api/portfolios/stats                 # Get portfolio statistics
GET    /api/portfolios/user/me               # Get current user's portfolios
GET    /api/portfolios/check-slug/:slug      # Check slug availability
GET    /api/portfolios/public/:slug          # Get public portfolio
GET    /api/portfolios/:id                   # Get portfolio by ID
PUT    /api/portfolios/:id                   # Update portfolio
DELETE /api/portfolios/:id                   # Delete portfolio
PUT    /api/portfolios/:id/publish           # Publish portfolio
PUT    /api/portfolios/:id/unpublish         # Unpublish portfolio

Example: Create Portfolio

curl -X POST http://localhost:5000/api/portfolios \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -d '{
    "title": "My Design Portfolio",
    "description": "A showcase of my creative work",
    "templateId": "echelon",
    "customData": {
      "hero": {
        "title": "Jane Designer",
        "subtitle": "UI/UX Designer & Creative Director"
      }
    }
  }'

---

Template System Endpoints (NEW)

GET    /api/templates                        # Get all templates (with filters)
GET    /api/templates/categories             # Get template categories
GET    /api/templates/default                # Get default template
GET    /api/templates/:id                    # Get template by ID
GET    /api/templates/:id/schema             # Get template schema only
POST   /api/templates/:id/validate           # Validate content against schema
POST   /api/templates/:id/rating             # Rate template (1-5 stars)

# Admin endpoints
POST   /api/templates                        # Create new template
PUT    /api/templates/:id                    # Update template
DELETE /api/templates/:id                    # Deactivate template
POST   /api/templates/:id/version            # Create new template version

Example: Get Templates with Filters

# Get all minimal category templates
curl "http://localhost:5000/api/templates?category=minimal"

# Get premium templates with specific tags
curl "http://localhost:5000/api/templates?isPremium=true&tags=modern,clean"

Example: Validate Portfolio Content

curl -X POST http://localhost:5000/api/templates/echelon/validate \
  -H "Content-Type: application/json" \
  -d '{
    "content": {
      "hero": {
        "title": "My Portfolio",
        "subtitle": "Designer & Developer"
      },
      "about": {
        "name": "John Doe",
        "bio": "Passionate about creating beautiful designs"
      }
    }
  }'

---

Case Study Endpoints

POST   /api/case-studies                     # Create case study
GET    /api/case-studies/:id                 # Get case study by ID
GET    /api/case-studies/portfolio/:portfolioId/project/:projectId
PUT    /api/case-studies/:id                 # Update case study
DELETE /api/case-studies/:id                 # Delete case study
GET    /api/case-studies/public/:portfolioSlug/:projectId

---

Site Publishing Endpoints

# Site publishing
POST   /api/sites/publish                    # Deploy to Vercel
POST   /api/sites/sub-publish                # Publish to local subdomain ⭐
POST   /api/sites/debug-generate             # Debug HTML generation
DELETE /api/sites/unpublish/:portfolioId     # Unpublish site

# Site access
GET    /api/sites/:subdomain                 # Get site by subdomain
GET    /api/sites/:subdomain/raw-html        # Get raw HTML
GET    /api/sites/:subdomain/case-study/:projectId/raw-html

# Configuration
GET    /api/sites/status                     # Get publishing status
GET    /api/sites/config                     # Get site configuration
PUT    /api/sites/config                     # Update site configuration
POST   /api/sites/analytics/view             # Record site view

Example: Gmail-Style Subdomain Publishing ⭐

curl -X POST http://localhost:5000/api/sites/sub-publish \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -d '{
    "portfolioId": "6501234567890abcdef12345",
    "subdomain": "jane-designer"
  }'

Result:

✅ Site published at: aurea.tool/jane-designer
📁 Files generated in: generated-files/jane-designer/

---

PDF Export Endpoints

GET    /api/pdf/portfolio/:portfolioId       # View portfolio PDF (inline)
GET    /api/pdf/portfolio/:portfolioId/complete # Complete PDF with case studies
GET    /api/pdf/portfolio/:portfolioId/download # Force download PDF
GET    /api/pdf/portfolio/:portfolioId/info  # Get PDF generation info
POST   /api/pdf/cleanup                      # Cleanup old PDFs (admin)

Example: Export Portfolio as PDF

# View PDF in browser
curl http://localhost:5000/api/pdf/portfolio/6501234567890abcdef12345

# Download PDF file
curl -O http://localhost:5000/api/pdf/portfolio/6501234567890abcdef12345/download

---

Media Upload Endpoints

POST   /api/upload/single                    # Upload single image
POST   /api/upload/multiple                  # Upload multiple images

Example: Upload Image

curl -X POST http://localhost:5000/api/upload/single \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -F "image=@/path/to/image.jpg"

---

AI PDF Processing Endpoints

POST   /api/proposal-extract/extract         # Extract data from PDF
GET    /api/proposal-extract/history         # Get extraction history
GET    /api/proposal-extract/test-gemini     # Test Gemini AI connection

Example: Extract Data from PDF

curl -X POST http://localhost:5000/api/proposal-extract/extract \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -F "pdf=@/path/to/proposal.pdf"

---

📖 API Documentation

🔗 Visit Swagger UI: http://localhost:5000/api-docs

Quick Start Guide (shown in Swagger):

1. Register: /api/auth/signup (no auth required)
2. Login: /api/auth/login (get JWT token)
3. Use token: Authorization: Bearer <token> header

Interactive Testing:

• ✅ All 65+ endpoints organized by tag
• ✅ Live testing directly in browser
• ✅ JWT token authentication support
• ✅ Request/response examples for each endpoint
• ✅ Standard response format documentation
• ✅ HTTP status code reference

---

🏗️ Architecture

🎯 Clean Architecture Implementation (October 2025)

Status: 80% Refactored to Clean Architecture ✅

AUREA Backend has been substantially refactored from MVC to Clean Architecture with clear separation of concerns. This ensures maintainability, testability, and scalability.

Request Flow Pattern

Route → Middleware Chain → Thin Controller → Service (Business Logic) → Repository (Data Access) → Model → Database

Architecture Layers

1. API Layer (src/api/, routes & controllers)

   • Controllers: Thin HTTP handlers (< 360 lines each, mostly routing)
   • Routes: Endpoint definitions with middleware chains
   • Middlewares: Request processing, validation, authentication

2. Core Layer (src/core/)

   • Services (11 total): Business logic, orchestration, validation
   • Repositories (5 total): Data access abstraction, query building
   • Domain: Business entities and rules

3. Shared Layer (src/shared/)

   • Exceptions: Custom error classes (NotFoundError, ValidationError, ForbiddenError, etc.)
   • Constants: HTTP status codes, error codes
   • Utils: ResponseFormatter for consistent API responses
   • DTOs: Data Transfer Objects for API contracts

4. Infrastructure Layer (src/infrastructure/)

   • Logging: Structured logging system with sanitization
   • Database: Connection management
   • External Services: Cloudinary, Vercel, Redis integrations

5. Configuration (src/config/)

   • Centralized configuration management
   • Environment variable validation
   • Service initialization

Refactoring Achievements

• ✅ 10/10 Controllers refactored to thin pattern
• ✅ 11 Services created with all business logic
• ✅ 5 Repositories for data access abstraction
• ✅ 100% Centralized Configuration (no scattered process.env)
• ✅ 99% Structured Logging (console.log replaced)
• ✅ Consistent Error Handling with custom exceptions
• ✅ Standardized Responses via responseFormatter

New Development Patterns

Using Services (Clean Architecture):

// ✅ CORRECT: Service handles business logic
import portfolioService from '../core/services/PortfolioService.js';
import responseFormatter from '../shared/utils/responseFormatter.js';

export const createPortfolio = async (req, res, next) => {
  try {
    const portfolio = await portfolioService.createPortfolio(req.user._id, req.body);
    return responseFormatter.created(res, { portfolio }, 'Portfolio created');
  } catch (error) {
    next(error); // Error middleware handles it
  }
};

Using Repositories:

// ✅ CORRECT: Service uses repository for data access
class PortfolioService {
  async getPortfolio(id) {
    const portfolio = await this.repository.findById(id);
    if (!portfolio) {
      throw NotFoundError.resource('Portfolio', id);
    }
    return portfolio;
  }
}

Using Custom Exceptions:

// ✅ CORRECT: Throw custom exceptions instead of returning errors
if (!portfolio) {
  throw NotFoundError.resource('Portfolio', portfolioId);
}
if (portfolio.userId.toString() !== userId) {
  throw ForbiddenError.ownershipRequired('portfolio');
}
if (slugTaken) {
  throw ConflictError.slugTaken(slug);
}

Using Structured Logging:

// ✅ CORRECT: Use structured logging
import logger from '../infrastructure/logging/Logger.js';

logger.info('Portfolio created', { portfolioId, userId });
logger.error('Database error', { error, context });
logger.service('PortfolioService', 'createPortfolio', { userId });

Project Structure

AUREA---Backend/
├── src/
│   ├── config/              # Centralized Configuration (Clean Architecture)
│   │   ├── index.js         # Configuration aggregator
│   │   ├── database.js      # MongoDB connection
│   │   ├── cloudinary.js    # Cloudinary setup
│   │   ├── swagger.js       # Swagger documentation config
│   │   ├── templateRegistry.js # Template registration
│   │   └── envValidator.js  # Environment validation
│   │
│   ├── controllers/         # API Layer - Thin HTTP handlers
│   │   ├── authController.js       # Auth HTTP handlers
│   │   ├── userController.js       # User HTTP handlers
│   │   ├── portfolioController.js  # Portfolio HTTP handlers
│   │   ├── templateController.js   # Template HTTP handlers
│   │   ├── caseStudyController.js  # Case study HTTP handlers
│   │   ├── siteController.js       # Site publishing HTTP handlers
│   │   ├── pdfExportController.js  # PDF HTTP handlers
│   │   ├── uploadController.js     # Upload HTTP handlers
│   │   └── proposalExtract*.controller.js # AI extraction handlers
│   │
│   ├── core/                # Core Layer - Business Logic & Data Access
│   │   ├── services/        # Services (11 total) - Business Logic
│   │   │   ├── AuthService.js
│   │   │   ├── PortfolioService.js
│   │   │   ├── UserService.js
│   │   │   ├── TemplateService.js
│   │   │   ├── CaseStudyService.js
│   │   │   ├── SubdomainService.js
│   │   │   ├── SiteService.js
│   │   │   ├── PremiumService.js
│   │   │   ├── PDFExportService.js
│   │   │   ├── UploadService.js
│   │   │   └── ProposalExtractService.js
│   │   │
│   │   └── repositories/    # Repositories (5 total) - Data Access
│   │       ├── UserRepository.js
│   │       ├── PortfolioRepository.js
│   │       ├── TemplateRepository.js
│   │       ├── CaseStudyRepository.js
│   │       └── SiteRepository.js
│   │
│   ├── models/              # Data Models (Mongoose schemas)
│   │   ├── User.js          # User authentication & profile
│   │   ├── Portfolio.js     # Portfolio with template support
│   │   ├── Template.js      # Dynamic template system
│   │   ├── CaseStudy.js     # Case study documentation
│   │   └── Site.js          # Published site records
│   │
│   ├── routes/              # API Route Definitions (9 route files)
│   │   ├── authRoutes.js
│   │   ├── userRoutes.js
│   │   ├── portfolioRoutes.js
│   │   ├── templateRoutes.js
│   │   ├── caseStudyRoutes.js
│   │   ├── siteRoutes.js
│   │   ├── pdfRoutes.js
│   │   ├── uploadRoutes.js
│   │   └── proposalExtract.routes.js
│   │
│   ├── middleware/          # Express Middleware
│   │   ├── auth.js          # JWT authentication & authorization
│   │   ├── ownership.js     # Resource ownership verification
│   │   ├── validation.js    # Request validation rules
│   │   ├── errorHandler.js  # Centralized error handling
│   │   ├── rateLimiter.js   # Endpoint rate limiting
│   │   ├── requestLogger.js # Request/response logging
│   │   ├── logSanitizer.js  # Sanitize sensitive data in logs
│   │   ├── bruteForcePrevention.js # Brute force protection
│   │   ├── premium.js       # Premium-only route protection
│   │   ├── upload.js        # Multer file upload configuration
│   │   └── validatePortfolioContent.js # Portfolio content validation
│   │
│   ├── shared/              # Shared Layer - Reusable Components
│   │   ├── exceptions/      # Custom exception classes
│   │   │   ├── ApplicationError.js
│   │   │   ├── ValidationError.js
│   │   │   ├── NotFoundError.js
│   │   │   ├── UnauthorizedError.js
│   │   │   ├── ForbiddenError.js
│   │   │   ├── ConflictError.js
│   │   │   └── index.js
│   │   │
│   │   ├── constants/       # Application constants
│   │   │   ├── httpStatus.js
│   │   │   └── errorCodes.js
│   │   │
│   │   └── utils/           # Shared utilities
│   │       └── responseFormatter.js # Standardized API responses
│   │
│   ├── infrastructure/      # Infrastructure Layer
│   │   └── logging/         # Structured logging system
│   │       └── Logger.js    # Logger with sanitization
│   │
│   ├── services/            # Root-level Services (special cases)
│   │   ├── templateEngine.js # PDF template rendering (Puppeteer)
│   │   (Note: Use src/core/services/* for new services)
│   │
│   └── utils/               # Helper Utilities
│       ├── cache.js         # Redis caching with graceful degradation
│       ├── slugGenerator.js # Slug generation & validation
│       ├── subdomainValidator.js # Subdomain format validation
│       └── templateValidator.js  # Template schema validation
│
├── services/                # Business services (root level)
│   ├── deploymentService.js # Vercel deployment
│   ├── pdfGenerationService.js # PDF export
│   └── templateConvert.js   # Template HTML conversion
│
├── seeds/                   # Database seeders
│   ├── templateSeeds.js     # Seed initial templates
│   └── migratePortfolios.js # Migration scripts
│
├── scripts/                 # Utility scripts
│   └── upgrade-user-to-premium.js
│
├── test/                    # Test suites
│   ├── test-template-system.js
│   ├── test-custom-subdomain.js
│   ├── test-publish-flow.js
│   └── test-*.js
│
├── uploads/                 # Temporary file uploads
│   └── pdfs/
│
├── generated-files/         # Published site files (Gmail-style subdomains)
│   ├── {subdomain}/
│   │   ├── index.html
│   │   └── case-study-*.html
│
├── server.js                # Application entry point
├── package.json             # Dependencies and scripts
├── swagger.yaml             # OpenAPI specification
├── .env                     # Environment variables (gitignored)
├── .env.example             # Environment template
└── README.md                # This file

System Architecture Diagram

Clean Architecture Flow:

┌─────────────────────────────────────────────────────────────┐
│                        CLIENT LAYER                          │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐      │
│  │   React      │  │   Mobile     │  │   External   │      │
│  │  Frontend    │  │    Apps      │  │     APIs     │      │
│  └──────────────┘  └──────────────┘  └──────────────┘      │
└─────────────────────────────────────────────────────────────┘
                              ↕ HTTP/HTTPS
┌─────────────────────────────────────────────────────────────┐
│                  ⭐ API GATEWAY LAYER                        │
│  ┌────────────────────────────────────────────────────────┐ │
│  │  Express.js Server (Port 5000)                         │ │
│  │  - CORS, Helmet, Compression                           │ │
│  │  - Rate Limiting (Express-Rate-Limit)                  │ │
│  │  - Request Logging & Error Handling                    │ │
│  └────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
                              ↕
┌─────────────────────────────────────────────────────────────┐
│         ⭐ MIDDLEWARE CHAIN (Clean Architecture)             │
│  ┌────────────────────────────────────────────────────────┐ │
│  │  1. Log Sanitizer → 2. Brute Force Prevention         │ │
│  │  3. JWT Auth → 4. Ownership Check → 5. Rate Limit     │ │
│  │  6. Request Validation → 7. Error Handler              │ │
│  └────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
                              ↕
┌─────────────────────────────────────────────────────────────┐
│          ⭐ API LAYER (Thin Controllers - 10/10)             │
│          Route Handlers (< 30 lines each)                   │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐      │
│  │AuthCtrl  │ │UserCtrl  │ │PortCtrl  │ │TplCtrl   │      │
│  │(Auth)    │ │(Users)   │ │(Portfolio)│ │(Templates)│     │
│  └──────────┘ └──────────┘ └──────────┘ └──────────┘      │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐      │
│  │ CSCtrl   │ │SiteCtrl  │ │PDFCtrl   │ │UploadCtrl│      │
│  │(CaseStd) │ │(Sites)   │ │(PDF)     │ │(Upload)  │      │
│  └──────────┘ └──────────┘ └──────────┘ └──────────┘      │
│  ┌──────────┐                                               │
│  │ AICtrl   │ (Proposal Extract)                           │
│  └──────────┘                                               │
└─────────────────────────────────────────────────────────────┘
                              ↕
┌─────────────────────────────────────────────────────────────┐
│        ⭐ CORE LAYER - SERVICE/REPOSITORY PATTERN            │
│  ┌────────────────────────────────────────────────────────┐ │
│  │ SERVICES (11 total) - Business Logic Layer             │ │
│  │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐       │ │
│  │ │AuthService  │ │PortService  │ │UserService  │       │ │
│  │ │ (Auth Biz)  │ │(Port Biz)   │ │(User Biz)   │       │ │
│  │ └─────────────┘ └─────────────┘ └─────────────┘       │ │
│  │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐       │ │
│  │ │TplService   │ │CSService    │ │SiteService  │       │ │
│  │ │(Tmpl Biz)   │ │(CaseStd Biz)│ │(Site Biz)   │       │ │
│  │ └─────────────┘ └─────────────┘ └─────────────┘       │ │
│  │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐       │ │
│  │ │SubService   │ │PDFService   │ │UploadService       │ │
│  │ │(Subdomain)  │ │(PDF Export) │ │(Image Upload)      │ │
│  │ └─────────────┘ └─────────────┘ └─────────────┘       │ │
│  │                                                         │ │
│  │ REPOSITORIES (5 total) - Data Access Layer             │ │
│  │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐       │ │
│  │ │UserRepo     │ │PortRepo     │ │TplRepo      │       │ │
│  │ │(User Data)  │ │(Port Data)  │ │(Tmpl Data)  │       │ │
│  │ └─────────────┘ └─────────────┘ └─────────────┘       │ │
│  │ ┌─────────────┐ ┌─────────────┐                        │ │
│  │ │CSRepo       │ │SiteRepo     │                        │ │
│  │ │(CS Data)    │ │(Site Data)  │                        │ │
│  │ └─────────────┘ └─────────────┘                        │ │
│  └────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
                              ↕
┌─────────────────────────────────────────────────────────────┐
│    ⭐ SHARED LAYER (Reusable Infrastructure)                 │
│  ┌─────────────────┐ ┌──────────────┐ ┌───────────────┐   │
│  │  Exceptions     │ │  Constants   │ │  Utils        │   │
│  │ (Custom Errors) │ │ (HTTP Status)│ │(ResponseFmt)  │   │
│  └─────────────────┘ └──────────────┘ └───────────────┘   │
└─────────────────────────────────────────────────────────────┘
                              ↕
┌─────────────────────────────────────────────────────────────┐
│  ⭐ INFRASTRUCTURE LAYER (External Integration)              │
│  ┌────────────────────────────────────────────────────────┐ │
│  │  Structured Logging & Sanitization                    │ │
│  │  Database Connection Management                        │ │
│  │  Cloudinary, Redis, Vercel Integration                │ │
│  └────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
                              ↕
┌─────────────────────────────────────────────────────────────┐
│                    DATABASE & MODELS                         │
│  ┌────────────────────────────────────────────────────────┐ │
│  │  Mongoose ODM with Schema Definitions                  │ │
│  │  - User Model        - Portfolio Model                 │ │
│  │  - Template Model    - CaseStudy Model                 │ │
│  │  - Site Model        (5 Models Total)                  │ │
│  └────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
                              ↕
┌─────────────────────────────────────────────────────────────┐
│                    EXTERNAL SERVICES                         │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐      │
│  │ MongoDB  │ │  Redis   │ │Cloudinary│ │ Google   │      │
│  │ Database │ │  Cache   │ │  CDN     │ │ Gemini   │      │
│  └──────────┘ └──────────┘ └──────────┘ └──────────┘      │
│  ┌──────────┐ ┌──────────┐                                 │
│  │  Vercel  │ │Puppeteer │                                 │
│  │  Deploy  │ │ PDF Gen  │                                 │
│  └──────────┘ └──────────┘                                 │
└─────────────────────────────────────────────────────────────┘

Request Flow Example (Clean Architecture)

User Creates Portfolio (POST /api/portfolios):

1. Client → Request with JWT token
             ↓
2. Express Middleware Stack:
   - Log Sanitizer: Sanitize sensitive data
   - Brute Force Prevention: Check IP rate limits
   - Auth Middleware: Verify JWT, attach user to req.user
   - Ownership Middleware: (N/A for create)
   - Rate Limiter: Check endpoint limits (30/min for portfolios)
   - Request Validator: Validate request body schema
             ↓
3. Router → Route to portfolioController.create
             ↓
4. Controller (Thin Handler):
   - Receives validated request (req.body, req.user)
   - Calls portfolioService.createPortfolio(userId, data)
   - Catches errors and passes to error handler (next(error))
             ↓
5. Service Layer (PortfolioService):
   - Business logic: Validate template exists
   - Business logic: Validate content against template schema
   - Call repository.create(portfolioData)
   - Throws custom exception if validation fails
             ↓
6. Repository Layer (PortfolioRepository):
   - Data access abstraction
   - Call Portfolio.create(data) on Mongoose model
   - Return created document
             ↓
7. Database (MongoDB):
   - Create portfolio document
   - Apply schema validation
   - Persist to database
             ↓
8. Back through Service:
   - Service returns portfolio object
   - Logger records success
   - Cache (Redis) invalidates user's portfolio list
             ↓
9. Back through Controller:
   - Response formatter: responseFormatter.created(res, data)
   - Format response with standardized structure
             ↓
10. Client ← Success response with portfolio data

Example Controller Code (Clean Architecture):

export const create = async (req, res, next) => {
  try {
    // Service handles all business logic
    const portfolio = await portfolioService.createPortfolio(
      req.user._id,
      req.body
    );
    // Standardized response formatting
    return responseFormatter.created(res, { portfolio }, 'Portfolio created');
  } catch (error) {
    // Error middleware handles all error types
    next(error);
  }
};

Example Service Code (Clean Architecture):

class PortfolioService {
  async createPortfolio(userId, data) {
    // Validate template exists
    const template = await this.repository.findTemplate(data.templateId);
    if (!template) {
      throw NotFoundError.resource('Template', data.templateId);
    }

    // Validate content against template schema
    if (!this.validateContent(template.schema, data.content)) {
      throw ValidationError.invalidContent('Portfolio content does not match template schema');
    }

    // Repository handles data creation
    const portfolio = await this.repository.create({
      ...data,
      userId
    });

    logger.info('Portfolio created', { portfolioId: portfolio._id, userId });
    return portfolio;
  }
}

---

🧪 Complete API Endpoints (65+ Total)

🧪 Testing

Available Test Scripts

# Run all tests
npm test

# Run specific test suites
npm run test:integration          # Frontend integration tests
npm run test:user                 # User management tests

# Run template system tests
node test/test-template-system.js

# Test portfolio creation flow
node test/test-publish-flow.js

# Test PDF generation
node test/test-pdf-generation.js

# Test Vercel deployment
node test/test-vercel-deployment-improved.js

# Test custom subdomain publishing
node test/test-custom-subdomain.js

Test Coverage

The test suite covers:

• ✅ Authentication - Signup, login, token validation
• ✅ User Management - Profile CRUD operations
• ✅ Portfolio System - Create, read, update, delete portfolios
• ✅ Template System - Template selection, validation, rating
• ✅ Case Studies - Case study creation and HTML generation
• ✅ Publishing - Vercel and subdomain deployment
• ✅ PDF Export - Portfolio and case study PDF generation
• ✅ Media Upload - Image upload to Cloudinary
• ✅ AI Processing - PDF extraction with Gemini AI

Manual Testing

Using Swagger UI:

1. Navigate to http://localhost:5000/api-docs
2. Click "Authorize" button
3. Enter JWT token: Bearer YOUR_TOKEN_HERE
4. Test any endpoint directly from the browser

Using cURL:

# Health check
curl http://localhost:5000/health

# Register user
curl -X POST http://localhost:5000/api/auth/signup \
  -H "Content-Type: application/json" \
  -d '{"name":"Test User","email":"[email protected]","password":"Test123!"}'

# Login
curl -X POST http://localhost:5000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","password":"Test123!"}'

Using Postman:

1. Import the Swagger JSON: http://localhost:5000/api-docs.json
2. Set up environment variables for BASE_URL and JWT_TOKEN
3. Run the collection

---

📚 Additional Documentation

Comprehensive Guides

• Template System Guide - Complete template management documentation
• Frontend Integration Guide - React integration patterns
• Integration Success Outcomes - Expected results and KPIs
• PDF Performance Guide - PDF generation optimization
• Subdomain Publishing Guide - Gmail-style subdomain setup

API Documentation

• Swagger UI: http://localhost:5000/api-docs
• OpenAPI Spec: swagger.yaml

Development Guides

• Backend Improvements - Recent enhancements
• Dynamic Template Refactor - Template system architecture

---

🤝 Contributing

We welcome contributions! Here's how you can help:

Getting Started

1. Fork the repository

   git clone https://github.com/your-username/aurea-backend.git

2. Create a feature branch

   git checkout -b feature/your-feature-name

3. Make your changes

   • Follow the existing code style
   • Add tests for new features
   • Update documentation

4. Commit your changes

   git commit -m "feat: add amazing feature"

5. Push to your fork

   git push origin feature/your-feature-name

6. Create a Pull Request

Commit Message Convention

Follow Conventional Commits:

• feat: - New feature
• fix: - Bug fix
• docs: - Documentation changes
• style: - Code style changes (formatting)
• refactor: - Code refactoring
• test: - Adding or updating tests
• chore: - Maintenance tasks

Examples:

feat: add template rating system
fix: resolve JWT token expiration issue
docs: update API documentation
refactor: improve portfolio controller logic

Code Style Guidelines

• Use ES6+ features
• Follow ESLint configuration
• Use async/await for asynchronous code
• Add comments for complex logic
• Keep functions small and focused
• Use meaningful variable names

Pull Request Guidelines

• Provide clear description of changes
• Reference related issues
• Ensure all tests pass
• Update documentation if needed
• Add screenshots for UI changes

---

📄 License

This project is licensed under the ISC License.

---

👥 Team & Support

Development Team

AUREA Development Team

• Backend Architecture & API Design
• Template System Development
• Security & Performance Optimization

Contact & Support

• 📧 Email: [email protected]
• 🐛 Bug Reports: GitHub Issues
• 💬 Discussions: GitHub Discussions
• 📖 Documentation: Full Documentation

Reporting Issues

When reporting issues, please include:

1. Description - Clear description of the issue
2. Steps to Reproduce - How to reproduce the issue
3. Expected Behavior - What you expected to happen
4. Actual Behavior - What actually happened
5. Environment - Node version, OS, etc.
6. Logs - Relevant error messages or logs
7. Screenshots - If applicable

---

🙏 Acknowledgments

Technologies & Libraries

• Express.js - Web framework
• MongoDB & Mongoose - Database
• JWT - Authentication
• Cloudinary - Media management
• Puppeteer - PDF generation
• Google Gemini AI - AI processing
• Redis - Caching
• Swagger - API documentation

Inspiration & Resources

• Portfolio design best practices
• Modern web architecture patterns
• RESTful API design principles

---

📊 Project Statistics

• 65+ API Endpoints
• 5 Database Models
• 9 Route Modules
• 10+ Middleware Functions
• 3+ AI-Powered Features
• 100% RESTful Design
• Production Ready

---

Made with ❤️ by the AUREA Team

⭐ Star on GitHub • 🐛 Report Bug • 📖 Documentation

---

📝 Change Log

Version 1.0.0 (October 2025)

✨ Major Features

• Complete authentication and user management system
• Dynamic template system with schema validation
• Portfolio CRUD with template support
• Case study management with smart HTML generation
• Dual publishing system (Vercel + local subdomain)
• PDF export with multiple template options
• AI-powered PDF extraction with Gemini AI
• Professional image upload with Cloudinary

🛡️ Security Enhancements

• JWT authentication with role-based access
• Rate limiting on all endpoints
• Input validation and sanitization
• Helmet security headers
• CORS configuration
• Ownership verification middleware

⚡ Performance Improvements

• Redis caching implementation
• Database query optimization
• Response compression
• Connection pooling
• Graceful degradation for optional services

📚 Documentation

• Complete Swagger/OpenAPI documentation
• Comprehensive README with examples
• Integration guides for frontend
• Template system documentation
• Deployment guides

---

Made with ❤️ by the AUREA Development Team

Version 1.0.0 | Production Ready | Last Updated: October 20, 2025