KelanaAI

AI-powered travel planning. Drop a pin on a map, set a budget and a travel style, and get a day-by-day itinerary — plus a chat assistant that answers travel questions from a curated document library and shows its sources.

• Plan a trip — destination, length, budget, month, style and group become a day-by-day schedule with costs, a budget breakdown and transport guidance.
• Ask the assistant — multi-turn chat grounded in an Amazon Bedrock Knowledge Base (visa checklists, customs and payment guides, city guides). Every answer lists the passages it was written from.

Demo

---

Architecture

Two independently-run halves:

	Stack	Runs on
backend/	FastAPI, SQLAlchemy, PostgreSQL, Amazon Bedrock	port 8000
frontend/	Next.js 16 (App Router), React 19, TypeScript, Tailwind CSS 4	port 3000

Itinerary generation is three stages, not one call: an outline call fixes each day's theme, area, anchors, dinner and evening venue; then day-batches (5 days each) and the tips/food/budget/transport sections run concurrently against that outline; the results are merged. This exists because amazon.nova-lite-v1:0 emits at most 5,000 output tokens per request — a single call could not produce a fully-detailed month-long trip. See services/bedrock_service.py.

The assistant retrieves passages from the Knowledge Base and then answers with them prepended, because retrieve_and_generate is not offered for managed knowledge bases. See services/kb_service.py.

---

Prerequisites

• Python 3.11+
• Node.js 20+
• PostgreSQL 14+ (local) or a Neon database
• An AWS account with Amazon Bedrock model access for amazon.nova-lite-v1:0

---

Local setup

1. Database

createdb kelana          # or point DATABASE_URL at a Neon database

2. Backend

cd backend
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env     # then fill it in — see the table below
uvicorn main:app --reload

init_db() runs at import and creates any missing tables, so a fresh database needs nothing else. The scripts in backend/migrations/ are only for evolving an already-populated database — there is no Alembic:

python migrations/add_conversations_and_messages.py
python migrations/add_conversations_and_messages.py --downgrade

3. Frontend

cd frontend
npm install
cp .env.example .env.local
npm run dev

Open http://localhost:3000.

---

Environment variables

backend/.env

Variable	Required	What it's for
DATABASE_URL	yes	Postgres connection string. Neon needs ?sslmode=require.
AWS_REGION	yes	Bedrock region, e.g. ap-southeast-2. Missing this crashes at import.
MODEL_ID	yes	Generation model, e.g. amazon.nova-lite-v1:0.
AWS_BEARER_TOKEN_BEDROCK	yes	Bedrock API key. Authorizes bedrock-runtime only.
JWT_SECRET_KEY	yes	Signs session tokens. Use a long random string.
AWS_ACCESS_KEY_ID	for the assistant	SigV4 credentials. The bearer token above cannot call the Knowledge Base APIs.
AWS_SECRET_ACCESS_KEY	for the assistant	Pairs with the above.
KNOWLEDGE_BASE_ID	for the assistant	The managed Bedrock Knowledge Base to query.
PIXABAY_API_KEY	for trip photos	Pixabay key. Unset means trips are created without a photo.
FRONTEND_URL	for deploys	Extra CORS origins, comma-separated. Vercel's own *.vercel.app hostnames are matched by a regex in main.py and don't need listing.

frontend/.env.local

Variable	Required	What it's for
NEXT_PUBLIC_API_URL	yes	Backend base URL. Defaults to http://localhost:8000.
NEXT_PUBLIC_MAP_TILE_URL	yes	Leaflet tile server URL.

NEXT_PUBLIC_* values are inlined at build time — changing one in a hosting dashboard does nothing until you redeploy.

---

Commands

# backend/
uvicorn main:app --reload

# frontend/
npm run dev
npm run build
npm run lint
npm test
npx tsc --noEmit

---

Deployment

The frontend and backend deploy separately and only need to know each other's URLs.

Database — Neon

1. Create a project; copy the connection string from Connection Details.
2. Set it as DATABASE_URL, keeping ?sslmode=require.
3. Start the backend once — init_db() creates the schema.

database.py sets pool_pre_ping and pool_recycle because Neon drops idle connections and its free tier auto-suspends; without them the pool hands out a dead socket and the next query fails.

To copy local data up instead of starting empty:

pg_dump "postgresql://localhost:5432/kelana" --no-owner --no-privileges \
  | psql "<neon-connection-string>"

Backend — FastAPI Cloud

1. Set every backend/.env variable in the project's environment settings — .env is gitignored and is not deployed.
2. Deploy. FastAPI Cloud starts the app with the fastapi run CLI, which lives in the fastapi-cli package — this is why requirements.txt pins fastapi[standard] rather than bare fastapi. With plain fastapi the container crash-loops on RuntimeError: To use the fastapi command, please install "fastapi[standard]" and never passes a readiness probe.

Any other host works the same way, as long as it binds 0.0.0.0:$PORT.

Frontend — Vercel

1. Set Root Directory to frontend.
2. Add NEXT_PUBLIC_API_URL (your backend URL, no trailing slash) and NEXT_PUBLIC_MAP_TILE_URL.
3. Deploy — and redeploy after any change to those variables.

This is the beginning of the README. Read the rest at the original. Read the full README ↗