🗺️ Local Guide Platform API

A comprehensive backend API for connecting travelers with passionate local experts who offer authentic, personalized experiences. This platform empowers individuals to share their city's hidden gems, culture, and stories, allowing travelers to explore destinations like a local.

Postman Collection: Local Guide API Collection

🧱 Features

🔐 Authentication: JWT-based authentication with refresh tokens, password reset, and OTP verification
👥 Role-based Access Control: TOURIST, GUIDE, and ADMIN roles with appropriate permissions
📝 User Management: Complete profile management with role-specific fields (expertise, daily rate for guides, travel preferences for tourists)
🎯 Tour Listings: Create, update, delete, and manage tour listings with images, pricing, and availability
📅 Availability Management: Guides can set available dates/times for their tours
📖 Booking System: Complete booking workflow with status management (Pending, Confirmed, Completed, Cancelled)
💳 Payment Integration: Stripe integration for secure payment processing
⭐ Review & Rating: Post-tour review and rating system for guides
❤️ Wishlist: Tourists can save favorite listings
🏅 Badge System: Automated badge assignment for guides (Super Guide, Newcomer, Foodie Expert, etc.)
📊 Analytics & Stats: Comprehensive statistics for admins and guides
📧 Email Notifications: OTP verification and password reset via email
📸 File Uploads: Cloudinary integration for image uploads
🔍 Advanced Search: Filter listings by city, category, price range, and more
⚠️ Global Error Handling: Comprehensive error management and validation
🧱 Modular Architecture: Scalable and maintainable codebase structure
🔒 Security: Input validation, authentication middleware, and secure file handling

🧩 Tech Stack

Node.js + Express — Backend framework
TypeScript — Type-safe development
PostgreSQL + Prisma — Database with ORM
Zod — Schema validation
JWT — Authentication and authorization
Stripe — Payment processing
Cloudinary — Image storage and management
Multer — File upload handling
Node-cron — Scheduled tasks
dotenv — Environment configuration
ESLint — Code quality and linting
Render — Deployment

🛠️ Getting Started

# 1. Clone the repository
git clone <repository-url>
cd b5a8-server

# 2. Install dependencies
npm install

# 3. Configure environment variables
cp .env.example .env

# 4. Update .env with your configuration
PORT=5000
DATABASE_URL="postgresql://username:password@localhost:5432/local_guide_db"
NODE_ENV=development

# JWT
JWT_ACCESS_SECRET=your_access_secret
JWT_ACCESS_EXPIRES=3d
JWT_REFRESH_SECRET=your_refresh_secret
JWT_REFRESH_EXPIRES=10d

# BCRYPT
BCRYPT_SALT_ROUND=10

# SUPER ADMIN
SUPER_ADMIN_EMAIL=super@localguide.com
SUPER_ADMIN_PASSWORD=your_super_admin_password

# Express Session
EXPRESS_SESSION_SECRET=your_session_secret

# Frontend URL
FRONTEND_URL=http://localhost:3000

# CLOUDINARY
CLOUDINARY_CLOUD_NAME=your_cloud_name
CLOUDINARY_API_KEY=your_api_key
CLOUDINARY_API_SECRET=your_api_secret

# STRIPE
STRIPE_SECRET_KEY=your_stripe_secret_key
STRIPE_WEBHOOK_SECRET=your_stripe_webhook_secret
STRIPE_APPLICATION_FEE_PERCENTAGE=10
STRIPE_CURRENCY=usd


# 5. Prisma migration
npx prisma migrate dev

# 6. Generate Prisma client
npx prisma generate

# 7. Seed database (optional)
npm run db:seed

# 8. Start development server
npm run dev

👤 Dummy Users for Testing

Email and password for some dummy users:
// ADMIN
email: super@next.com
password: ph@123456

// TOURIST
email: john.tourist@localguide.com
password: tourist123

// GUIDE
email: ahmed.guide@localguide.com
password: guide123

📁 Project Structure

b5a8-server/
├── src/
│   ├── app/
│   │   ├── config/
│   │   │   ├── cloudinary.config.ts
│   │   │   ├── db.ts
│   │   │   ├── env.ts
│   │   │   ├── multer.config.ts
│   │   │   ├── redis.config.ts
│   │   │   └── stripe.config.ts
│   │   ├── interfaces/
│   │   │   ├── error.ts
│   │   │   ├── error.types.ts
│   │   │   ├── index.d.ts
│   │   │   └── pagination.ts
│   │   ├── middlewares/
│   │   │   ├── checkAuth.ts
│   │   │   ├── dbConnection.ts
│   │   │   ├── globalErrorHandler.ts
│   │   │   ├── notFound.ts
│   │   │   └── validateRequest.ts
│   │   ├── modules/
│   │   │   ├── auth/
│   │   │   │   ├── auth.controller.ts
│   │   │   │   ├── auth.routes.ts
│   │   │   │   ├── auth.service.ts
│   │   │   │   └── auth.validation.ts
│   │   │   ├── user/
│   │   │   │   ├── user.constant.ts
│   │   │   │   ├── user.controller.ts
│   │   │   │   ├── user.routes.ts
│   │   │   │   ├── user.service.ts
│   │   │   │   └── user.validation.ts
│   │   │   ├── listing/
│   │   │   │   ├── listing.constant.ts
│   │   │   │   ├── listing.controller.ts
│   │   │   │   ├── listing.routes.ts
│   │   │   │   ├── listing.service.ts
│   │   │   │   └── listing.validation.ts
│   │   │   ├── availability/
│   │   │   │   ├── availability.constant.ts
│   │   │   │   ├── availability.controller.ts
│   │   │   │   ├── availability.routes.ts
│   │   │   │   ├── availability.service.ts
│   │   │   │   └── availability.validation.ts
│   │   │   ├── booking/
│   │   │   │   ├── booking.constant.ts
│   │   │   │   ├── booking.controller.ts
│   │   │   │   ├── booking.routes.ts
│   │   │   │   ├── booking.service.ts
│   │   │   │   └── booking.validation.ts
│   │   │   ├── payment/
│   │   │   │   ├── payment.constant.ts
│   │   │   │   ├── payment.controller.ts
│   │   │   │   ├── payment.cron.ts
│   │   │   │   ├── payment.routes.ts
│   │   │   │   ├── payment.service.ts
│   │   │   │   ├── payment.validation.ts
│   │   │   │   └── payment.webhook.ts
│   │   │   ├── review/
│   │   │   │   ├── review.constant.ts
│   │   │   │   ├── review.controller.ts
│   │   │   │   ├── review.routes.ts
│   │   │   │   ├── review.service.ts
│   │   │   │   └── review.validation.ts
│   │   │   ├── wishlist/
│   │   │   │   ├── wishlist.constant.ts
│   │   │   │   ├── wishlist.controller.ts
│   │   │   │   ├── wishlist.routes.ts
│   │   │   │   └── wishlist.service.ts
│   │   │   ├── badge/
│   │   │   │   ├── badge.constant.ts
│   │   │   │   ├── badge.controller.ts
│   │   │   │   ├── badge.routes.ts
│   │   │   │   └── badge.service.ts
│   │   │   ├── stats/
│   │   │   │   ├── stats.controller.ts
│   │   │   │   ├── stats.routes.ts
│   │   │   │   └── stats.service.ts
│   │   │   └── otp/
│   │   │       ├── otp.controller.ts
│   │   │       ├── otp.routes.ts
│   │   │       ├── otp.service.ts
│   │   │       └── otp.validation.ts
│   │   ├── routes/
│   │   │   └── index.ts
│   │   └── utils/
│   │       ├── catchAsync.ts
│   │       ├── errorHelpers/
│   │       │   ├── AppError.ts
│   │       │   ├── handleClientError.ts
│   │       │   ├── handleValidationError.ts
│   │       │   └── handleZodError.ts
│   │       ├── jwt/
│   │       │   ├── jwt.ts
│   │       │   ├── setCookie.ts
│   │       │   └── userTokens.ts
│   │       ├── paginationHelper.ts
│   │       ├── pick.ts
│   │       ├── seedDummyUsers.ts
│   │       ├── seedSuperAdmin.ts
│   │       ├── sendEmail.ts
│   │       └── sendResponse.ts
│   ├── app.ts
│   └── server.ts
├── prisma/
│   ├── migrations/
│   ├── schema.prisma
│   └── prisma.config.ts
├── sample-data/
│   ├── availabilities-bookings-payments-reviews.ts
│   ├── cleanAndSeed.ts
│   ├── listings.ts
│   ├── seedAll.ts
│   └── wishlists.ts
├── postman/
│   └── Local_Guide_API.postman_collection.json
├── docs/
│   ├── LocalGuide.md
│   ├── README.md
│   ├── STRIPE_ENV_SETUP.md
│   └── STRIPE_INTEGRATION.md
├── package.json
└── tsconfig.json

👤 User Roles

Role	Responsibilities
`TOURIST`	Search tours, book guides, write reviews, manage wishlist
`GUIDE`	Create and manage tour listings, set availability, accept bookings
`ADMIN`	Manage users, listings, bookings, view statistics, manage badges

📡 API Endpoints

Base URL: /api/v1

🔐 Authentication

Method	Endpoint	Description	Auth Required
POST	`/auth/register`	Register user (Tourist/Guide)	No
POST	`/auth/login`	Login user	No
POST	`/auth/refresh-token`	Refresh JWT token	No
POST	`/auth/logout`	Logout user	Yes
POST	`/auth/forgot-password`	Request password reset	No
POST	`/auth/change-password`	Change password	Yes
POST	`/auth/reset-password`	Reset password with token	Yes

📧 OTP (Optional)

Method	Endpoint	Description	Auth Required
POST	`/otp/send`	Send OTP to email	No
POST	`/otp/verify`	Verify OTP	No

👤 Users

Method	Endpoint	Description	Auth Required	Role
GET	`/user/me`	Get logged-in user profile	Yes	Any
GET	`/user/:id`	Get user by ID	No	-
GET	`/user/top-rated-guides`	Get top rated guides	No	-
GET	`/user/all-users`	Get all users (paginated)	Yes	ADMIN
PATCH	`/user/:id`	Update user profile	Yes	Owner/Any
PATCH	`/user/:id/block-user`	Block/unblock user	Yes	ADMIN
POST	`/user/create-admin`	Create new admin	Yes	ADMIN

🎯 Listings

Method	Endpoint	Description	Auth Required	Role
GET	`/listings`	Get all listings (with filters)	No	-
GET	`/listings/:id`	Get listing by ID	No	-
GET	`/listings/featured-cities`	Get featured cities	No	-
GET	`/listings/categories/distinct`	Get distinct categories with counts	No	-
GET	`/listings/my/listings`	Get my listings (paginated)	Yes	GUIDE
POST	`/listings`	Create new listing	Yes	GUIDE
PATCH	`/listings/:id`	Update listing	Yes	GUIDE
DELETE	`/listings/:id`	Delete listing	Yes	GUIDE

Query Parameters for GET /listings:

page - Page number (default: 1)
limit - Items per page (default: 10)
city - Filter by city
category - Filter by category (CULTURE, FOOD, ADVENTURE, etc.)
minPrice - Minimum price filter
maxPrice - Maximum price filter
search - Search in title/description

📅 Availabilities

Method	Endpoint	Description	Auth Required	Role
GET	`/availabilities`	Get all availabilities	No	-
GET	`/availabilities/:id`	Get availability by ID	No	-
GET	`/availabilities/my/availabilities`	Get my availabilities	Yes	GUIDE
POST	`/availabilities`	Create availability	Yes	GUIDE
POST	`/availabilities/bulk`	Create bulk availabilities	Yes	GUIDE
PATCH	`/availabilities/:id`	Update availability	Yes	GUIDE
DELETE	`/availabilities/:id`	Delete availability	Yes	GUIDE

Query Parameters for GET /availabilities:

listingId - Filter by listing ID
page - Page number
limit - Items per page

📖 Bookings

Method	Endpoint	Description	Auth Required	Role
POST	`/bookings`	Create booking request	Yes	TOURIST
GET	`/bookings/my-bookings`	Get my bookings	Yes	Any
GET	`/bookings`	Get all bookings (admin)	Yes	ADMIN
GET	`/bookings/:id`	Get booking by ID	Yes	Any
PATCH	`/bookings/:id/status`	Update booking status	Yes	GUIDE

Query Parameters for GET /bookings/my-bookings:

page - Page number
limit - Items per page
type - Filter by type (upcoming, past)
status - Filter by status (PENDING, CONFIRMED, COMPLETED, CANCELLED)

Booking Status Values:

PENDING - Awaiting guide confirmation
CONFIRMED - Guide accepted the booking
COMPLETED - Tour completed
CANCELLED - Booking cancelled

💳 Payments

Method	Endpoint	Description	Auth Required	Role
POST	`/payments/confirm`	Confirm payment with Stripe	Yes	TOURIST
GET	`/payments`	Get my payments	Yes	Any
GET	`/payments/booking/:bookingId`	Get payment by booking ID	Yes	Any
GET	`/payments/:id`	Get payment by ID	Yes	Any
POST	`/payments/:id/release`	Release payment to guide	Yes	GUIDE

Query Parameters for GET /payments:

page - Page number
limit - Items per page

Note: Payment processing is handled via Stripe. The webhook endpoint /webhook handles Stripe events.

⭐ Reviews

Method	Endpoint	Description	Auth Required	Role
GET	`/reviews`	Get all reviews	No	-
GET	`/reviews/:id`	Get review by ID	No	-
GET	`/reviews/my/reviews`	Get my reviews (as guide)	Yes	GUIDE
GET	`/reviews/reviewable-bookings`	Get reviewable bookings	Yes	TOURIST
GET	`/reviews/booking/:bookingId`	Get review by booking ID	No	-
GET	`/reviews/guide/:guideId`	Get reviews by guide ID	No	-
POST	`/reviews`	Create review	Yes	TOURIST
PATCH	`/reviews/:id`	Update review	Yes	TOURIST
DELETE	`/reviews/:id`	Delete review	Yes	TOURIST

Query Parameters for GET /reviews:

listingId - Filter by listing ID
page - Page number
limit - Items per page

Query Parameters for GET /reviews/my/reviews:

page - Page number
limit - Items per page
sortBy - Sort field (createdAt, rating)
sortOrder - Sort order (asc, desc)

❤️ Wishlist

Method	Endpoint	Description	Auth Required	Role
POST	`/wishlist`	Add listing to wishlist	Yes	TOURIST
GET	`/wishlist`	Get my wishlist	Yes	TOURIST
GET	`/wishlist/check/:listingId`	Check if listing in wishlist	Yes	TOURIST
DELETE	`/wishlist/:listingId`	Remove from wishlist	Yes	TOURIST

Query Parameters for GET /wishlist:

page - Page number
limit - Items per page

🏅 Badges

Method	Endpoint	Description	Auth Required	Role
GET	`/badges/guide/:guideId`	Get guide badges	No	-
POST	`/badges/guide/:guideId/recalculate`	Recalculate guide badges	Yes	ADMIN
POST	`/badges/recalculate-all`	Recalculate all badges	Yes	ADMIN

Badge Types:

SUPER_GUIDE - High ratings and many bookings
NEWCOMER - New guide on the platform
FOODIE_EXPERT - Expertise in food tours
CULTURE_MASTER - Expertise in cultural tours
ADVENTURE_SEEKER - Expertise in adventure tours

📊 Stats

Method	Endpoint	Description	Auth Required	Role
GET	`/stats/overview`	Get overview statistics	Yes	ADMIN
GET	`/stats/users`	Get user statistics	Yes	ADMIN
GET	`/stats/tourists`	Get tourist statistics	Yes	ADMIN
GET	`/stats/guides`	Get guide statistics	Yes	ADMIN
GET	`/stats/listings`	Get listing statistics	Yes	ADMIN
GET	`/stats/bookings`	Get booking statistics	Yes	ADMIN
GET	`/stats/revenue`	Get revenue statistics	Yes	ADMIN
GET	`/stats/profit`	Get profit statistics	Yes	ADMIN
GET	`/stats/guide-info`	Get guide info and stats	Yes	GUIDE

🗄️ Database Schema

User Model

id: Primary key
name: User's full name
email: Unique email address
password: Hashed password
phone: Optional phone number
picture: Profile picture URL
bio: User biography
languages: Array of languages spoken
role: User role (TOURIST, GUIDE, ADMIN)
isActive: Account status (ACTIVE, INACTIVE, BLOCKED)
isVerified: Email verification status
isDeleted: Soft delete flag
expertise: Array of expertise areas (Guide only)
dailyRate: Daily rate for guides
travelPreferences: Array of travel preferences (Tourist only)
stripeCustomerId: Stripe customer ID (Tourist only)

Listing Model

id: Primary key
title: Tour listing title
description: Tour description
itinerary: Detailed itinerary
tourFee: Tour fee amount
durationDays: Maximum duration in days
meetingPoint: Meeting point location
maxGroupSize: Maximum group size
city: City where tour is located
category: Tour category (CULTURE, FOOD, ADVENTURE, etc.)
images: Array of image URLs
isActive: Listing active status
guideId: Reference to Guide User

Availability Model

id: Primary key
startDateTime: Start date and time
endDateTime: End date and time
isAvailable: Availability status
listingId: Reference to Listing

Booking Model

id: Primary key
date: Booking date
numberOfGuests: Number of guests
status: Booking status (PENDING, CONFIRMED, COMPLETED, CANCELLED)
touristId: Reference to Tourist User
listingId: Reference to Listing
availabilityId: Reference to Availability

Payment Model

id: Primary key
amount: Payment amount
currency: Payment currency
status: Payment status
paymentIntentId: Stripe payment intent ID
bookingId: Reference to Booking
touristId: Reference to Tourist User
guideId: Reference to Guide User

Review Model

id: Primary key
rating: Rating (1-5)
comment: Review comment
bookingId: Reference to Booking
touristId: Reference to Tourist User
guideId: Reference to Guide User
listingId: Reference to Listing

Wishlist Model

id: Primary key
touristId: Reference to Tourist User
listingId: Reference to Listing

Badge Model

id: Primary key
type: Badge type
guideId: Reference to Guide User

🔒 Authentication

All protected endpoints require tokens in the cookies:

cookie: accessToken=<access_token>
cookie: refreshToken=<refresh_token>

Access tokens expire after the configured time (default: 3 days). Use the refresh token endpoint to obtain a new access token.

📝 Request/Response Format

Success Response

{
  "success": true,
  "statusCode": 200,
  "message": "Operation successful",
  "data": {
    // Response data
  },
  "meta": {
    // Pagination metadata (if applicable)
    "page": 1,
    "limit": 10,
    "total": 100,
    "totalPages": 10
  }
}

Error Response

{
  "success": false,
  "statusCode": 400,
  "message": "Error message",
  "errorDetails": {
    // Detailed error information
  },
  "stack": "Error stack (development only)"
}

🧪 Testing

Use the provided Postman collection to test all endpoints:

Import postman/Local_Guide_API.postman_collection.json into Postman
Set the base_url variable to your API URL (default: http://localhost:5000/api/v1)
Start with authentication endpoints to get access tokens
Tokens are automatically saved to collection variables for subsequent requests

📚 Additional Documentation

🚀 Deployment

The application can be deployed to various platforms. Ensure all environment variables are properly configured in your deployment environment.

Build for Production

npm run build

Start Production Server

npm start

👨‍💻 Author

Faisal Akbar

Name		Name	Last commit message	Last commit date
Latest commit History 76 Commits
.vscode		.vscode
docs		docs
postman		postman
prisma		prisma
sample-data		sample-data
src		src
.env.example		.env.example
.gitignore		.gitignore
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json
prisma.config.ts		prisma.config.ts
render-build.sh		render-build.sh
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation

🗺️ Local Guide Platform API

🧱 Features

🧩 Tech Stack

🛠️ Getting Started

📁 Project Structure

👤 User Roles

📡 API Endpoints

🔐 Authentication

📧 OTP (Optional)

👤 Users

🎯 Listings

📅 Availabilities

📖 Bookings

💳 Payments

⭐ Reviews

❤️ Wishlist

🏅 Badges

📊 Stats

🗄️ Database Schema

User Model

Listing Model

Availability Model

Booking Model

Payment Model

Review Model

Wishlist Model

Badge Model

🔒 Authentication

📝 Request/Response Format

Success Response

Error Response

🧪 Testing

📚 Additional Documentation

🚀 Deployment

Build for Production

Start Production Server

👨‍💻 Author

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages