For AI agents: the docs index is at https://volt-docs.travclan.com/llms.txt. Append .md to any documentation page URL to get its markdown version.
| Problem | Tell Cursor |
|---|
| Cursor does nothing when the project opens | Expected — the prompt files only act on a command. Type build in the chat. |
| Build starts without asking the setup questions | Stop and type build again. Confirm Plan mode first, then answer the setup wizard (API key, logging, MongoDB, payments, daily refresh, build scope) before clicking Build. |
| Only the backend was built | Run build frontend. If you chose "Backend and frontend" in the wizard, the frontend should be built automatically after the backend is healthy. |
| Docker or Node.js is missing | Run ./run.sh setup from the repo root. It installs Docker and Node.js if they are missing. |
| Problem | Tell Cursor |
|---|
./run.sh says permission denied | Run chmod +x run.sh, then ./run.sh again. |
| Port 8000 or 5173 is already in use | Run ./run.sh stop, close any other app using those ports, then ./run.sh. |
/health does not show "mongo":"ok" | Local MongoDB: run ./run.sh stop && ./run.sh to start the tg-mongo container. Remote MongoDB: check the connection string and allow network access from your IP (and 0.0.0.0/0 for Vercel). Or type add mongodb to repair it. |
Changes to .env don't apply | ./run.sh restarts the API and the website when backend/.env or frontend/.env changes. If it doesn't, run ./run.sh stop && ./run.sh. |
| Problem | Tell Cursor |
|---|
| No packages load, or calls return 401 | Run configure env and paste a valid FD_API_KEY. The backend must send x-api-key: Bearer <FD_API_KEY>. Check ./run.sh logs for UPSTREAM_AUTH. |
| Works in sandbox but fails in production | Switch both together in backend/.env: FD_API_BASE_URL=https://holidays-volt-tp.travclan.com and the production FD_API_KEY, with FD_ENV=production. Never mix a sandbox key with the production URL. |
| Prices or seats look out of date | Run ./run.sh sync to refresh package data now. Keep the daily refresh on (SYNC_ENABLED=true). |
| Browser shows a CORS error | APP_ALLOWED_ORIGINS in backend/.env must include the website's address, and the backend must allow the X-Guest-Key header. |
| Problem | Tell Cursor |
|---|
| Total does not match the calculator | Pricing lives in backend/app/services/pricing.py and frontend/src/lib/pricing.ts; keep them identical. Run ./run.sh test and fix any failing pricing case. |
| Day-wise plan is missing hotels or flights | Build the plan with buildItinerary(): hotels from Package Details on their day_of_trip, the primary flight's outbound on Day 1 and inbound on the last day, other flights (e.g. inter-city flights) on their day_of_trip. |
| Choosing an add-on does not update everything | Keep add-on choices in the trip store only. The itinerary card, "Staying at" rows, "Your extras", the total, Review and the checkout request must all read from it. |
| Problem | Tell Cursor |
|---|
| Payment done but booking stays "Paid" | The Book call failed or timed out; the booking moves to "Refund needed" with an error code. With Stripe locally, make sure stripe listen --forward-to localhost:8000/api/v1/payments/stripe/webhook is running. |
| My Bookings is empty in another browser | Expected — there is no sign-in yet. Bookings are linked to the browser that made them. |
| Booking stays "Received" and never confirms | Expected until the booking webhook signature details are configured; /api/public/fd-webhook returns 501 until then. Confirmation happens offline through your ACM. |
| Problem | Tell Cursor |
|---|
deploy app stops before deploying | Fix what it reports: placeholder secrets, the app not running locally, failing tests or a failed frontend build. Then run deploy app again. |
| Production deploy is refused | Production needs Stripe; the mock checkout works only for Preview. Run add stripe, then deploy app. |
| Deployed site can't load packages | Check VITE_API_BASE_URL on the frontend project points to the deployed API, and APP_ALLOWED_ORIGINS on the backend project includes the website's address. Redeploy the backend. |
| Package data never refreshes on Vercel | The Vercel Cron job calls /api/public/fd-sync daily with CRON_SECRET. Check CRON_SECRET is set on the backend project. |
