VoyageCraft Project: AI-Powered Itinerary Generator

Live Links:

• API Endpoint: https://voyagecraft-api.naahid-sha.workers.dev/
• Live UI Demo: https://voyagecraft-ui.pages.dev/

---

🎯 Project Goal

VoyageCraft is a complete Full-Stack JavaScript project, designed as a technical test for an AI engineering role. The primary goal of this project is to demonstrate the ability to build modern, serverless, and asynchronous applications.

This application allows users to receive a detailed, day-by-day travel itinerary generated by artificial intelligence by simply entering a destination and the number of travel days.

🏛️ Overall Architecture

This project follows a modern, decoupled architecture where the backend (API) and frontend (UI) are two completely independent entities. These two parts communicate with each other through a standard API and use a shared database for asynchronous data exchange.

📁 Complete Project Structure

Below is the complete structure of files and folders, along with a description for each part:

<pre>
/
├── api/                  # Backend Project (Cloudflare Worker)
│   ├── node_modules/     # Backend project dependencies
│   ├── src/              # Main worker source code
│   │   ├── index.js      # Entry file and main API router
│   │   ├── routes/
│   │   │   └── itinerary.js # Logic for the /itinerary route
│   │   ├── services/
│   │   │   ├── firestore.js # Service for connecting and working with Firestore
│   │   │   └── llm.js       # Service for connecting to the OpenAI API
│   │   └── utils/
│   │       └── uuid.js      # Helper utility for generating UUIDs
│   ├── .dev.vars         # Environment variables for local testing (should not be in Git)
│   ├── .gitignore        # Files that should not be committed to Git
│   ├── package.json      # List of backend dependencies and scripts
│   ├── package-lock.json # Exact version of dependencies
│   └── wrangler.toml     # Cloudflare Worker configuration file
│
└── ui/                   # Frontend Project (React.js)
    ├── node_modules/     # Frontend project dependencies
    ├── public/           # Static files
    │   └── index.html    # Main HTML template for the application
    ├── src/              # Main React source code
    │   ├── App.css       # Main application styles
    │   ├── App.jsx       # Main component and application page
    │   ├── index.js      # Main React entry file
    │   └── services/
    │       └── firebase.js # Service for connecting to Firebase for the UI
    ├── .env              # Environment variables for local execution (should not be in Git)
    ├── .gitignore        # Files that should not be committed to Git
    ├── package.json      # List of frontend dependencies and scripts
    └── package-lock.json # Exact version of dependencies
</pre>

☁️ Backend: api/

This section is the brain and processing engine of the project, implemented as a serverless service on Cloudflare Workers.

• Main Task: Receiving user requests, communicating with external services (AI and database), and performing heavy operations in the background.
• Key Technologies:
  • JavaScript: The primary language of the application.
  • Cloudflare Workers: A serverless platform for running code on Cloudflare's global network with high speed and scalability.
  • OpenAI API: For generating itinerary content using Large Language Models (LLMs).
  • Google Cloud Firestore: As a NoSQL database for storing the status and final results of travel plans.
  • Google Auth Library: For secure and standard authentication with Google services.
• Key Feature: Asynchronous architecture. The API immediately returns a jobId to the user upon receiving a request and continues the time-consuming process of generating the itinerary in the background (ctx.waitUntil). This provides a very fast user experience.

🖥️ Frontend: ui/

This section is the face of the project and the user interface that the user directly interacts with. It is a Single Page Application (SPA) built with React.js.

• Main Task: Providing a simple form to receive user input, sending requests to the backend API, and displaying the status and final results in real-time.
• Key Technologies:
  • React.js: A powerful JavaScript library for building interactive user interfaces.
  • Firebase SDK (Client): For establishing a live, direct connection with the Firestore database.
  • Cloudflare Pages: A web hosting platform for quick and secure project deployment via GitHub.
• Key Feature: Reactive. By using the useEffect hook in React and the onSnapshot function from Firebase, the user interface automatically reacts to changes in the database (e.g., status changing from processing to completed) and updates itself without needing a page refresh.

🔗 How the Components Connect

The magic of this project lies in the intelligent connection between the backend and frontend:

1. The UI sends a POST request to the API.
2. The API immediately returns a jobId to the UI.
3. The API, in the background, creates a record with the same jobId in Firestore and starts working with OpenAI.
4. As soon as the UI receives the jobId, it opens a live communication channel with Firestore and listens to that specific record.
5. When the API finishes its work and updates the record in Firestore, Firestore immediately sends the new data to the UI, and the result is displayed to the user.

This architecture creates a completely modern, scalable, and efficient system.