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.

WayFy relies on environment variables to wire together its Flask backend and Vite-powered React frontend without hardcoding sensitive credentials or deployment-specific URLs. Each side of the stack has its own .env file: backend/.env controls the Python process (database connection, JWT secrets, third-party API keys, and CORS policy), while frontend/.env exposes a small set of public values to the browser bundle through Vite’s VITE_ prefix convention. Copy the .env.example files provided in each directory and fill in the values described below before running either service.
The following variables are required — WayFy will refuse to start or will malfunction without them:
  • JWT_SECRET_KEY — the backend raises a RuntimeError at startup if this is missing.
  • DATABASE_URL — without a valid connection string, SQLAlchemy cannot initialize the database pool.
  • VITE_MAPBOX_TOKEN — the map canvas will fail to load, breaking every map-dependent feature.

​
Backend Variables

Place these in backend/.env. The Flask development server and any production WSGI host (e.g. Gunicorn on Render) will read them from the process environment. 
DATABASE_URL=postgres://username:password@localhost:5432/wayfy
FLASK_APP=src/app.py
FLASK_APP_KEY="replace-with-a-long-random-string"
FLASK_DEBUG=1
DEBUG=TRUE
JWT_SECRET_KEY="replace-with-a-secure-secret"
JWT_ACCESS_TOKEN_EXPIRES_HOURS=1
CORS_ALLOWED_ORIGINS=https://wayfy.onrender.com,http://localhost:3000
GROQ_API_KEY=gsk_...
CONTACT_EMAIL=hello@wayfy.app
CLOUDINARY_CLOUD_NAME=your_cloud_name
CLOUDINARY_API_KEY=your_api_key
CLOUDINARY_API_SECRET=your_api_secret
GOOGLE_PLACES_KEY=your_google_places_key
VariableRequiredDefaultDescription
DATABASE_URL✅ Yes—SQLAlchemy connection URI. postgres:// is automatically converted to postgresql:// at startup.
JWT_SECRET_KEY✅ Yes—Secret used to sign and verify JWT tokens. Use a long, random string in production.
FLASK_APPYes—Entry point for the Flask CLI. Must be set to src/app.py.
FLASK_APP_KEYYes—Flask SECRET_KEY used for session signing and CSRF protection.
FLASK_DEBUGNo0Set to 1 to enable the Werkzeug debugger and auto-reloader. Never enable in production.
DEBUGNoFALSEAdditional debug flag consumed by app logic. Mirror FLASK_DEBUG in development.
JWT_ACCESS_TOKEN_EXPIRES_HOURSNo1Lifetime of issued access tokens in hours. Increase for longer sessions or decrease for tighter security.
CORS_ALLOWED_ORIGINSNohttp://localhost:3000Comma-separated list of origins permitted by Flask-CORS. Add your production frontend URL here.
CLOUDINARY_CLOUD_NAMENo*—Cloudinary account identifier. Required when accessibility photo or trip cover image uploads are enabled.
CLOUDINARY_API_KEYNo*—Cloudinary API key. Required alongside CLOUDINARY_CLOUD_NAME.
CLOUDINARY_API_SECRETNo*—Cloudinary API secret. Required alongside CLOUDINARY_CLOUD_NAME.
GROQ_API_KEYNo*—API key for the Groq/Llama AI assistant. Required for the AI trip-planning features.
CONTACT_EMAILNo—Email address used by the contact/support form backend handler.
GOOGLE_PLACES_KEYNo*—Google Places API key used by the utility route for place lookups. Required for place-search features powered by Google.
Variables marked No* are optional in the sense that the server will start without them, but the features that depend on them (photo uploads, AI assistant, place search) will return errors at runtime if the keys are absent.

​
Frontend Variables

Place these in frontend/.env. Vite only injects variables prefixed with VITE_ into the browser bundle — any variable without that prefix is ignored and will be undefined at runtime. 
VITE_BASENAME=/
VITE_BACKEND_URL=http://localhost:3001
VITE_MAPBOX_TOKEN=pk.eyJ1IjoiZXhhbXBsZSIsImEiOiJleGFtcGxlIn0.example
VITE_GEOAPIFY_KEY=your_geoapify_key
VariableRequiredDefaultDescription
VITE_BACKEND_URL✅ Yes—Base URL for all fetch calls to the Flask API. Do not include a trailing slash. Example: https://api.wayfy.app. Locally the Flask dev server runs on port 3001.
VITE_MAPBOX_TOKEN✅ Yes—Mapbox GL JS access token. Obtain one from mapbox.com. The map will not render without it.
VITE_GEOAPIFY_KEYNo*—API key for Geoapify geocoding and place autocomplete. Required for the search-and-autocomplete features on the trip planner. Not included in the default frontend/.env.example but referenced in the codebase.
VITE_BASENAMENo/React Router basename. Set to a sub-path (e.g. /app) if the frontend is served from a non-root URL.
When deploying the frontend to a static host (Netlify, Vercel, Render static sites), set VITE_BACKEND_URL to your production backend URL in the host’s environment variable panel. Vite bakes these values into the compiled bundle at build time — changing them after vite build requires a rebuild.

​
Setting Up for Local Development

1

Copy the example files

Duplicate both .env.example files to create your local .env files:
cp backend/.env.example backend/.env
cp frontend/.env.example frontend/.env
2

Configure the backend

Open backend/.env and fill in at minimum:
  • DATABASE_URL — point to your local PostgreSQL or SQLite instance
  • JWT_SECRET_KEY — any long, random string works locally
  • FLASK_APP_KEY — any string works for local development
DATABASE_URL=postgres://postgres:postgres@localhost:5432/wayfy
JWT_SECRET_KEY=local-dev-secret-change-in-production
FLASK_APP_KEY=local-app-key
FLASK_DEBUG=1
3

Configure the frontend

Open frontend/.env and set the backend URL and your Mapbox token. The Flask dev server runs on port 3001 by default:
VITE_BACKEND_URL=http://localhost:3001
VITE_MAPBOX_TOKEN=pk.eyJ1IjoiZXhhbXBsZSIsImEiOiJleGFtcGxlIn0.example
4

Verify the setup

Start the backend and confirm it boots without errors:
cd backend && pipenv run start
Then start the frontend dev server:
cd frontend && npm run dev
If JWT_SECRET_KEY is missing, the backend will throw a RuntimeError immediately on startup — this is intentional to prevent running an insecure instance.

​
Production Checklist

Rotate JWT Secret

Use a cryptographically random secret for JWT_SECRET_KEY in production (e.g. openssl rand -hex 32). A weak or default secret allows token forgery.

Restrict CORS Origins

Set CORS_ALLOWED_ORIGINS to only your production frontend domain. Wildcards (*) allow any origin to call your API.

Disable Debug Mode

Set FLASK_DEBUG=0 and DEBUG=FALSE in production. The Werkzeug debugger exposes an interactive Python console if left enabled.

Secure Cloudinary Credentials

Store CLOUDINARY_API_SECRET in your hosting provider’s secret manager, not in version-controlled files. The .env file is listed in .gitignore by default.

Build docs developers (and LLMs) love

Get started for freeTalk to us