Lb1/backend_api_specification(luxe)

# 📖 Luxe Platform - Backend API Specification & Technical Documentation

This document provides a comprehensive technical specification for building the backend RESTful API services and database architecture for **Luxe**.

---

## 1. Executive Summary & System Architecture

### 1.1 Overview
Luxe is a multi-tier platform connecting **Users** (members/visitors) with **Clients** (service providers/listed profiles) and managed by **Admins**.

### 1.2 User Roles & Access Rights Matrix
| Role | Code Identifier | Permissions & Capabilities |
| :--- | :--- | :--- |
| **User** | `user` | Browse profiles, search with filters, save favorite listings, write reviews, interact with blog/forum, send messages. |
| **Client** | `advertiser` / `client` | All `user` capabilities + create and manage listed profile(s), upload gallery media, set availability & pricing, request verification, view analytics. |
| **Admin** | `admin` / `super_admin` | System-wide management, verify client profiles, moderate user content, full CRUD for Blogs & Forum, manage Cities & Categories, view dashboard analytics & audit logs. |

---

## 2. API Design Conventions & Protocols

* **Base URL**: `https://api.luxe.com/api/v1`
* **Transport**: HTTPS with TLS 1.3
* **Authentication**: JSON Web Tokens (JWT)
  * Header: `Authorization: Bearer <access_token>`
  * Access Token expiry: 15–60 minutes
  * Refresh Token expiry: 7–30 days (stored in HttpOnly, Secure Cookie)

### Standard Response Schemas

#### Success (`200 OK`, `201 Created`)
```json
{
  "success": true,
  "message": "Operation executed successfully",
  "data": { ... }
}
```

#### Paginated List Response
```json
{
  "success": true,
  "data": [ ... ],
  "pagination": {
    "total": 245,
    "page": 1,
    "pageSize": 20,
    "hasMore": true
  }
}
```

#### Error Response (`400 Bad Request`, `401 Unauthorized`, `403 Forbidden`, `404 Not Found`, `422 Unprocessable Entity`, `500 Internal Error`)
```json
{
  "success": false,
  "message": "Validation Error",
  "errors": [
    {
      "field": "email",
      "message": "Email address is already in use"
    }
  ]
}
```

---

## 3. Complete API Endpoint Catalog

---

### 🔑 Module 1: Authentication & Identity (`/auth`)

| Method | Endpoint | Access Level | Description |
| :--- | :--- | :--- | :--- |
| `POST` | `/auth/register` | Public | Register new user as `USER` or `CLIENT`. Returns access token & user object. |
| `POST` | `/auth/login` | Public | Authenticate user credentials. Sets HttpOnly refresh token cookie. |
| `POST` | `/auth/logout` | Authenticated | Revoke refresh token & invalidate current session. |
| `POST` | `/auth/refresh-token` | Public | Exchange refresh token cookie for a new access token. |
| `POST` | `/auth/forgot-password` | Public | Send password reset link or OTP to user email. |
| `/auth/reset-password` | `POST` | Public | Reset password using reset token/OTP. |
| `/auth/verify-otp` | `POST` | Authenticated | Verify email or phone number OTP code. |
| `/auth/me` | `GET` | Authenticated | Get current authenticated user profile & permissions. |

---

### 👤 Module 2: User Account & Favorites (`/users`)

| Method | Endpoint | Access Level | Description |
| :--- | :--- | :--- | :--- |
| `GET` | `/users/profile` | Authenticated | Fetch logged-in user profile metadata. |
| `PUT` | `/users/profile` | Authenticated | Update user display name, avatar, bio, and preferences. |
| `GET` | `/users/favorites` | User | Get paginated list of user's saved/bookmarked client profiles. |
| `POST` | `/users/favorites/:profileId` | User | Add client profile to user favorites. |
| `DELETE` | `/users/favorites/:profileId` | User | Remove client profile from user favorites. |
| `PUT` | `/users/change-password` | Authenticated | Update user password (requires old password). |
| `GET` | `/users/notifications` | Authenticated | Fetch notifications for current user. |

---

### 💋 Module 3: Client & Listed Profile Management (`/clients`)
*Dedicated to `CLIENT` accounts to manage their public listing.*

| Method | Endpoint | Access Level | Description |
| :--- | :--- | :--- | :--- |
| `GET` | `/clients/my-profile` | Client | Get client's listing details, completion status, and verification state. |
| `POST` | `/clients/my-profile` | Client | Create listed profile draft. |
| `PUT` | `/clients/my-profile` | Client | Full update of listed profile (name, age, city, area, priceFrom, tagline, categories, languages, height). |
| `PATCH` | `/clients/my-profile/status` | Client | Toggle online availability (`isOnline: true/false`). |
| `POST` | `/clients/my-profile/gallery` | Client | Upload & append image/video to profile gallery. |
| `DELETE` | `/clients/my-profile/gallery/:mediaId` | Client | Delete image/video from gallery. |
| `POST` | `/clients/my-profile/verification` | Client | Submit verification photos/documents for Admin approval. |
| `GET` | `/clients/analytics` | Client | Fetch client analytics (profile views, unique visitors, phone clicks, favorite counts). |

---

### 🔍 Module 4: Public Directory & Search (`/profiles`, `/search`, `/cities`, `/categories`)

| Method | Endpoint | Access Level | Description |
| :--- | :--- | :--- | :--- |
| `GET` | `/search/profiles` | Public | Multi-filter profile search (Query params: `query`, `city`, `area`, `categories[]`, `ageMin`, `ageMax`, `priceMin`, `priceMax`, `verified`, `online`, `premium`, `rating`, `sortBy`, `page`, `pageSize`). |
| `GET` | `/profiles/featured` | Public | Fetch featured & high-ranking client profiles. |
| `/profiles/trending` | `GET` | Public | Fetch trending/popular client profiles. |
| `GET` | `/profiles/:slug` | Public | Get full public profile information by unique slug. |
| `GET` | `/profiles/:slug/reviews` | Public | Get reviews and aggregate ratings for a client profile. |
| `POST` | `/profiles/:slug/reviews` | User | Submit a review & rating (1 to 5 stars) for a client profile. |
| `GET` | `/cities` | Public | Fetch active cities with listing counts and cover images. |
| `GET` | `/categories` | Public | Fetch all available profile service categories and icons. |

---

### 📰 Module 5: Blog & CMS (`/blogs`)

| Method | Endpoint | Access Level | Description |
| :--- | :--- | :--- | :--- |
| `GET` | `/blogs` | Public | Fetch paginated published blog posts (filters: `category`, `tag`, `search`). |
| `GET` | `/blogs/:slug` | Public | Get single blog post by slug with author info and reading time. |
| `POST` | `/blogs/:id/like` | Authenticated | Toggle like on a blog post. |
| `GET` | `/blogs/:id/comments` | Public | Fetch comments on a blog post. |
| `POST` | `/blogs/:id/comments` | Authenticated | Post a comment on a blog post. |
| `GET` | `/blogs/categories` | Public | Fetch all blog categories. |

---

### 💬 Module 6: Forum & Community (`/forum`)

| Method | Endpoint | Access Level | Description |
| :--- | :--- | :--- | :--- |
| `GET` | `/forum/topics` | Public | Get forum discussion topics (supports sorting by `newest`, `popular`, `pinned`). |
| `GET` | `/forum/topics/:slug` | Public | View forum topic detail with replies thread. |
| `POST` | `/forum/topics` | Authenticated | Create a new discussion thread. |
| `POST` | `/forum/topics/:id/reply` | Authenticated | Add a reply to a discussion thread. |
| `POST` | `/forum/topics/:id/like` | Authenticated | Upvote/like a topic or reply. |

---

### 💬 Module 7: Messaging & Notifications (`/messages`, `/notifications`)

| Method | Endpoint | Access Level | Description |
| :--- | :--- | :--- | :--- |
| `GET` | `/messages/conversations` | Authenticated | Get list of direct message conversations. |
| `GET` | `/messages/conversations/:id` | Authenticated | Get message history with another user/client. |
| `POST` | `/messages/send` | Authenticated | Send a direct message. (Emits WebSockets event `new_message`). |
| `GET` | `/notifications` | Authenticated | Fetch notifications (unread & read). |
| `PATCH` | `/notifications/:id/read` | Authenticated | Mark notification as read. |
| `PATCH` | `/notifications/read-all` | Authenticated | Mark all notifications as read. |

---

### 📁 Module 8: Media & Cloud File Upload (`/media`)

| Method | Endpoint | Access Level | Description |
| :--- | :--- | :--- | :--- |
| `POST` | `/media/presigned-url` | Authenticated | Generate AWS S3 / Cloudinary presigned upload URL for client-side upload. |
| `POST` | `/media/upload` | Authenticated | Direct multipart form file upload endpoint (fallback). |

---

### 🛡️ Module 9: Admin Panel API Suite (`/admin`)

#### 9.1 Dashboard & Analytics
| Method | Endpoint | Access Level | Description |
| :--- | :--- | :--- | :--- |
| `GET` | `/admin/stats/overview` | Admin | Overall system counters (Total Users, Total Clients, Active Listings, Verification Queue, Revenue). |
| `GET` | `/admin/stats/growth` | Admin | Time-series data for registrations, pageviews, active subscriptions. |

#### 9.2 User & Client Moderation
| Method | Endpoint | Access Level | Description |
| :--- | :--- | :--- | :--- |
| `GET` | `/admin/users` | Admin | Get paginated list of all users with search, role filter (`USER`, `CLIENT`, `ADMIN`), status filter. |
| `GET` | `/admin/users/:id` | Admin | Get detailed user record, IPs, login logs, and associated profiles. |
| `PATCH` | `/admin/users/:id/status` | Admin | Update user status (`active`, `suspended`, `banned`). |
| `PATCH` | `/admin/users/:id/role` | Admin | Modify user role (e.g. promote to `ADMIN` or `CLIENT`). |

#### 9.3 Client Verification Queue & Profile Controls
| Method | Endpoint | Access Level | Description |
| :--- | :--- | :--- | :--- |
| `GET` | `/admin/verifications` | Admin | Get pending client verification requests with uploaded ID proofs. |
| `POST` | `/admin/verifications/:id/approve` | Admin | Approve verification (`isVerified = true`), notify client. |
| `POST` | `/admin/verifications/:id/reject` | Admin | Reject verification with reason note. |
| `PATCH` | `/admin/profiles/:id/premium` | Admin | Toggle client profile badge (`isPremium = true/false`). |
| `DELETE` | `/admin/profiles/:id` | Admin | Moderation action: Soft-delete or remove violating listing. |

#### 9.4 Blog CMS Management
| Method | Endpoint | Access Level | Description |
| :--- | :--- | :--- | :--- |
| `GET` | `/admin/blogs` | Admin | List all blog posts including drafts and scheduled posts. |
| `POST` | `/admin/blogs` | Admin | Create a new blog post (`title`, `slug`, `excerpt`, `content`, `coverImage`, `category`, `tags`). |
| `PUT` | `/admin/blogs/:id` | Admin | Edit existing blog post. |
| `DELETE` | `/admin/blogs/:id` | Admin | Delete blog post. |
| `POST` | `/admin/blogs/categories` | Admin | Create blog category. |

#### 9.5 Platform Meta Data Management (Cities & Categories)
| Method | Endpoint | Access Level | Description |
| :--- | :--- | :--- | :--- |
| `POST` | `/admin/cities` | Admin | Add new city to directory. |
| `PUT` | `/admin/cities/:id` | Admin | Edit city details, image, or slug. |
| `DELETE` | `/admin/cities/:id` | Admin | Delete city. |
| `POST` | `/admin/categories` | Admin | Add new profile category/service. |
| `PUT` | `/admin/categories/:id` | Admin | Edit category details. |
| `DELETE` | `/admin/categories/:id` | Admin | Delete category. |

#### 9.6 Moderation, Reports & Audit Logs
| Method | Endpoint | Access Level | Description |
| :--- | :--- | :--- | :--- |
| `GET` | `/admin/reviews` | Admin | Moderate user-submitted profile reviews. |
| `POST` | `/admin/reviews/:id/approve` | Admin | Approve published review. |
| `DELETE` | `/admin/reviews/:id` | Admin | Delete fake/inappropriate review. |
| `GET` | `/admin/audit-logs` | Admin | View system audit log of admin actions. |

---

## 4. Database Entity Schema Specification (PostgreSQL / Prisma / MongoDB)

### 4.1 `User`
* `id`: String (UUID / Primary Key)
* `email`: String (Unique, Indexed)
* `username`: String (Unique)
* `passwordHash`: String
* `role`: Enum (`user`, `client`, `admin`, `super_admin`)
* `isVerified`: Boolean (default: false)
* `isPremium`: Boolean (default: false)
* `createdAt`: Timestamp
* `updatedAt`: Timestamp

### 4.2 `Profile` (Client Listings)
* `id`: String (UUID)
* `userId`: String (Foreign Key -> User.id)
* `slug`: String (Unique, Indexed)
* `name`: String
* `age`: Integer
* `cityId`: String (Foreign Key -> City.id)
* `area`: String
* `avatar`: String (URL)
* `coverImage`: String (URL)
* `rating`: Float (default: 0.0)
* `reviewCount`: Integer (default: 0)
* `isVerified`: Boolean
* `isPremium`: Boolean
* `isOnline`: Boolean
* `priceFrom`: Float
* `currency`: String (default: 'USD')
* `height`: String
* `tagline`: String
* `categories`: String[] (Array of Category slugs)
* `languages`: String[]
* `createdAt`: Timestamp

### 4.3 `BlogPost`
* `id`: String (UUID)
* `slug`: String (Unique)
* `title`: String
* `excerpt`: Text
* `content`: Text
* `coverImage`: String (URL)
* `authorName`: String
* `authorAvatar`: String
* `category`: String
* `tags`: String[]
* `readingTime`: Integer (minutes)
* `likes`: Integer (default: 0)
* `publishedAt`: Timestamp

### 4.4 `City`
* `id`: String (UUID)
* `slug`: String (Unique)
* `name`: String
* `country`: String
* `profileCount`: Integer
* `image`: String (URL)

### 4.5 `Category`
* `id`: String (UUID)
* `slug`: String (Unique)
* `name`: String
* `icon`: String
* `profileCount`: Integer

---

## 5. Security & Implementation Best Practices

1. **Password Hashing**: Use **Argon2id** or **Bcrypt** with salt rounds >= 12.
2. **CORS Configuration**: Restrict origins to trusted domains (`https://luxe.com`).
3. **Rate Limiting**: Enforce 100 requests per 15-minute window for standard endpoints; 5 attempts per 15 minutes for `/auth/login`.
4. **Input Sanitization**: Validate all requests using `Zod` or `Joi` schemas to prevent SQL Injection and XSS.
5. **Real-time Engine**: Use **Socket.io** or WebSockets for messaging and online status events.