Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/jhonyes04/new-wayfy/llms.txt

Use this file to discover all available pages before exploring further.

This guide walks you through cloning the WayFy repository, configuring environment variables, running database migrations, and starting both the Flask backend and the Vite frontend on your local machine. The entire setup takes under ten minutes.

​
Prerequisites

Ensure the following are installed before you begin:
ToolVersionNotes
Node.js>= 20Required for the Vite frontend
Python3.13Required for the Flask backend
pipenvlatestManages Python virtualenv and dependencies
PostgreSQL14+SQLite works for quick local testing; PostgreSQL is required for production parity
GitanyTo clone the repository
WayFy is fully compatible with GitHub Codespaces. Open the repository in a Codespace and all prerequisites are pre-installed in the default environment. You can skip to Backend Setup immediately.

​
Backend Setup

1

Clone the repository and navigate to the backend

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

Install Python dependencies

pipenv install
This creates a virtual environment and installs all packages from the Pipfile.lock.
3

Configure environment variables

Copy the example file and fill in your values:
cp .env.example .env
Open .env and set the following variables:
VariableDescriptionExample
DATABASE_URLPostgreSQL connection stringpostgresql://user:pass@localhost:5432/wayfy
FLASK_APPEntry point for Flask CLIsrc/app.py
FLASK_APP_KEYFlask secret key for sessionsany long random string
FLASK_DEBUGEnable Flask debug mode (1 = on)1
JWT_SECRET_KEYSigns and verifies JWT tokens — requiredany long random string
JWT_ACCESS_TOKEN_EXPIRES_HOURSToken lifetime in hours1
CORS_ALLOWED_ORIGINSComma-separated allowed originshttp://localhost:3000
GROQ_API_KEYAPI key from console.groq.comgsk_...
CONTACT_EMAILAddress used in outbound emailshello@wayfy.app
CLOUDINARY_CLOUD_NAMEYour Cloudinary cloud name — required for image uploadsmy-cloud
CLOUDINARY_API_KEYCloudinary API key — required for image uploads123456789012345
CLOUDINARY_API_SECRETCloudinary API secret — required for image uploadsabc123...
JWT_SECRET_KEY is mandatory. The application raises a RuntimeError at startup if this variable is missing or empty.
4

Apply database migrations

pipenv run upgrade
This runs flask db upgrade and applies all Alembic migrations to the database defined in DATABASE_URL, creating all tables.
5

Seed test data (optional)

To populate the database with sample places, users, trips, and reviews for local development:
pipenv run insert-test-data
To create a specific number of test users:
flask insert-test-users 5
6

Start the Flask development server

pipenv run start
Flask starts on http://localhost:3001 and listens on all interfaces (0.0.0.0). You should see:
 * Serving Flask app 'src/app.py'
 * Running on all addresses (0.0.0.0)
 * Running on http://127.0.0.1:3001

​
Frontend Setup

1

Navigate to the frontend directory

Open a new terminal tab and, from the repository root:
cd wayfy/frontend
2

Install Node dependencies

pnpm install
3

Configure environment variables

cp .env.example .env
Set the following in .env:
VariableDescriptionValue
VITE_BACKEND_URLURL of the running Flask backendhttp://localhost:3001
VITE_MAPBOX_TOKENPublic token from account.mapbox.compk.eyJ1...
VITE_BASENAMEBase path for the React Router/
VITE_GEOAPIFY_KEYGeoapify API key for address autocomplete (optional — geocoding features are disabled without it)your_key_here
VITE_GEOAPIFY_KEY is not included in .env.example but is a real variable consumed by the GeoapifyAutocomplete component. Obtain a free key at geoapify.com. Address autocomplete silently degrades if the key is absent.
4

Start the Vite development server

npm run dev
Vite starts on http://localhost:3000 with hot module replacement enabled. You should see:
  VITE v5.x.x  ready in 300 ms

  ➜  Local:   http://localhost:3000/
  ➜  Network: http://192.168.x.x:3000/

​
Verify the Installation

Open your browser and confirm each of the following routes loads correctly:
URLExpected result
http://localhost:3000/WayFy landing page
http://localhost:3000/mapInteractive Mapbox accessibility map
http://localhost:3000/loginLogin form
http://localhost:3000/registerRegistration form
http://localhost:3001/Flask backend root (JSON or 404 — confirms API is alive)

​
Available Commands

​
Backend (pipenv scripts)

CommandUnderlying commandDescription
pipenv run startflask run -p 3001 -h 0.0.0.0Start Flask development server
pipenv run migrateflask db migrateGenerate a new Alembic migration from model changes
pipenv run upgradeflask db upgradeApply pending migrations to the database
pipenv run downgradeflask db downgradeRevert the most recent migration
pipenv run insert-test-dataflask insert-test-dataSeed the database with sample data
flask insert-test-users 5(CLI command)Create 5 test user accounts

​
Frontend (npm / pnpm scripts)

CommandDescription
npm run dev / npm run startStart the Vite dev server on port 3000 with HMR
npm run buildCompile a production build into frontend/dist/
npm run previewServe the production build locally for testing
npm run lintRun ESLint across the frontend source

Build docs developers (and LLMs) love

Get started for freeTalk to us