Quickstart

MayTravel is an AI-powered travel planning assistant that uses Google Gemini and RAG to help users plan their trips.

Prerequisites

Before you begin, ensure you have the following installed:

Node.js (v16 or higher)
PostgreSQL (v12 or higher)
npm, yarn, or pnpm package manager

Installation

Clone the repository

Clone the MayTravel repository to your local machine:

git clone https://github.com/morenojf/MayTravel.git
cd MayTravel/backend

Install dependencies

Install the required Node.js packages:

npm install

The main dependencies include:

express (v5.2.1) - Web application framework
pg (v8.16.3) - PostgreSQL client for Node.js

Set up PostgreSQL database

Create a new PostgreSQL database for MayTravel:

CREATE DATABASE MayTravel;

PostgreSQL is used for its flexibility with dynamic schema changes. If the AI adds new fields to itinerary tables, the database won’t break.

Configure your database connection in /src/databases/postgres-db/maytraveldb.mjs:

maytraveldb.mjs

import { Client } from 'pg'

const pgdb = new Client({
  user: 'postgres',
  password: 'admin',
  host: 'localhost',
  port: 5432,
  database: 'MayTravel'
})

await pgdb.connect()
export const db = pgdb

Update the database credentials (user, password, host, port) to match your PostgreSQL configuration before running the server.

Start the server

Start the backend server:

node src/app.mjs

You should see the following output:

Example app listening on port 3000

The server is now running at http://localhost:3000

Server Configuration

The MayTravel backend uses Express.js and is configured in /src/configs/server.mjs:

server.mjs

import express from 'express'
export const app = express()
export const port = 3000

The main application file (/src/app.mjs) sets up middleware and routing:

app.mjs

import {app, port} from "./configs/server.mjs"
import express from 'express'
import { routing } from "./configs/routing.mjs"

app.listen(port, () => {
  console.log(`Example app listening on port ${port}`)
})

app.use(express.json());
app.use('/', routing)

Making Your First API Call

Now that your server is running, let’s test the API endpoints.

Authentication

curl -X POST http://localhost:3000/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "username": "traveler123",
    "email": "traveler@example.com",
    "password": "securepassword"
  }'

Response:

{
  "message": "User registered succesfully"
}

curl -X POST http://localhost:3000/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "identifier": "traveler@example.com",
    "password": "securepassword"
  }'

Response:

{
  "message": "Login exitoso",
  "token": "JWT_GENERADO_AQUI",
  "user": {
    "user": "traveler123",
    "email": "traveler@example.com",
    "role": "user"
  }
}

User Management

Get all users
Get user by ID
Update user info
Delete user

curl http://localhost:3000/users

curl http://localhost:3000/users/1

curl -X PUT http://localhost:3000/users/1 \
  -H "Content-Type: application/json" \
  -d '{
    "username": "newtraveler123",
    "email": "newemail@example.com"
  }'

curl -X DELETE http://localhost:3000/users/1

Interests

Manage user interests for personalized travel recommendations:

Get all interests
Get user interests
Add interests to user
Create new interest

curl http://localhost:3000/interests

curl http://localhost:3000/users/1/interests

curl -X POST http://localhost:3000/users/1/interests \
  -H "Content-Type: application/json" \
  -d '{
    "interests_id": [1, 2, 3]
  }'

curl -X POST http://localhost:3000/interests \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Adventure Sports",
    "description": "Activities like hiking, climbing, etc."
  }'

Trips

Get all trips
Get user trips
Create a trip
Get trip by ID
Delete a trip

curl http://localhost:3000/trips

curl http://localhost:3000/users/1/trips

curl -X POST http://localhost:3000/users/1/trips \
  -H "Content-Type: application/json" \
  -d '{
    "destination": "Paris, France",
    "start_date": "2026-06-01",
    "end_date": "2026-06-10",
    "budget": 2000
  }'

curl http://localhost:3000/trips/1

curl -X DELETE http://localhost:3000/trips/1

Points of Interest (POIs)

Get all POIs
Create a POI
Update a POI
Delete a POI

curl http://localhost:3000/pois

curl -X POST http://localhost:3000/pois \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Eiffel Tower",
    "location": "Paris, France",
    "category": "Landmark"
  }'

curl -X PATCH http://localhost:3000/pois/1 \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Tour Eiffel",
    "description": "Iconic iron tower"
  }'

curl -X DELETE http://localhost:3000/pois/1

Stops

Create trip stops (itinerary items):

curl -X POST http://localhost:3000/stops \
  -H "Content-Type: application/json" \
  -d '{
    "trip_id": 1,
    "poi_id": 1,
    "order": 1,
    "duration_minutes": 120
  }'

Available API Routes

Here’s a complete reference of all available endpoints from /src/configs/routing.mjs:

Method	Endpoint	Description
Authentication
POST	`/auth/register`	Register a new user
POST	`/auth/login`	Login and receive authentication token
Users
GET	`/users`	Get all users
GET	`/users/:id`	Get user by ID
POST	`/users`	Create a new user
PUT	`/users/:id`	Update user information
DELETE	`/users/:id`	Delete a user
GET	`/users/:id/interests`	Get user interests
POST	`/users/:id/interests`	Add interests to user
GET	`/users/:id/trips`	Get user trips
Interests
GET	`/interests`	Get all interests
POST	`/interests`	Create a new interest
PUT	`/interests/:id`	Update an interest
DELETE	`/interests/:id`	Delete an interest
Trips
GET	`/trips`	Get all trips
GET	`/trips/:id`	Get trip by ID
POST	`/users/:id/trips`	Create a trip for a user
DELETE	`/trips/:id`	Delete a trip
POIs (Points of Interest)
GET	`/pois`	Get all POIs
POST	`/pois`	Create a new POI
PATCH	`/pois/:id`	Update a POI
DELETE	`/pois/:id`	Delete a POI
Stops
POST	`/stops`	Create a trip stop

Next Steps

API Reference

Explore detailed API documentation

Architecture

Understand the system architecture

Database Schema

Learn about the database structure

AI Integration

Discover how AI powers MayTravel

Troubleshooting

Database connection failed

Ensure PostgreSQL is running and the credentials in maytraveldb.mjs match your database configuration:

# Check if PostgreSQL is running
pg_isready

# Or on Linux
sudo systemctl status postgresql

Port 3000 already in use

Change the port in /src/configs/server.mjs:

export const port = 3001 // or any available port

Module import errors

Ensure you’re using Node.js v16 or higher and that the project is configured as ES modules (check "type": "module" in package.json).

CORS errors from frontend

The backend has CORS configured in /src/middlewares/cors.mjs. Update the origin if your frontend runs on a different port:

app.use(cors({
  origin: 'http://localhost:3000', // Update this
  credentials: true,
  methods: ['GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'OPTIONS'],
  allowedHeaders: ['Content-Type', 'Authorization'],
}))

Get Started

Core Features

Architecture

Prerequisites

Installation

Server Configuration

Making Your First API Call

Authentication

User Management

Interests

Trips

Points of Interest (POIs)

Stops

Available API Routes

Next Steps

API Reference

Architecture

Database Schema

AI Integration

Troubleshooting

Build docs developers (and LLMs) love

Get Started

Core Features

Architecture

​Prerequisites

​Installation

​Server Configuration

​Making Your First API Call

​Authentication

​User Management

​Interests

​Trips

​Points of Interest (POIs)

​Stops

​Available API Routes

​Next Steps

API Reference

Architecture

Database Schema

AI Integration

​Troubleshooting

Build docs developers (and LLMs) love

Prerequisites

Installation

Server Configuration

Making Your First API Call

Authentication

User Management

Interests

Trips

Points of Interest (POIs)

Stops

Available API Routes

Next Steps

Troubleshooting