I built Kartografer — an AI travel planner where you describe a trip and Gemini generates a full day-wise itinerary. You can then edit it, chat with the AI for suggestions, share a public link, and export a PDF travel proposal.

Here are the decisions that mattered most.

The one rule that held everything together

Every itinerary item has one boolean: isSelected.

isSelected: true  → final plan
isSelected: false → option/suggestion

That's it. But this single field flows through the entire app. Budget only sums selected items. Public pages, share links, and PDF export only show selected items. Moving something to the options panel doesn't delete it — it just flips the flag.

Without this, I'd have needed separate tables for draft vs final content, or conditional logic scattered everywhere. One field kept it clean.

Why the AI never directly edits a trip

The obvious approach: user sends a message → AI updates the database. Simple. And completely wrong.

If the AI can directly mutate your itinerary, one bad response silently corrupts your plan. So I built a proposal flow instead:

User sends chat message
→ Gemini returns a reply + structured proposedChanges JSON
→ Proposal saved as PENDING
→ UI shows a preview card
→ User clicks Apply
→ Separate server action re-validates JSON + re-checks ownership
→ DB updates run + budget recalculated

The chat action never touches the itinerary. The apply action doesn't trust the proposal — it validates everything from scratch. Worst case: the AI returns garbage, the user sees a bad suggestion card and dismisses it. The trip stays untouched.

Long trips needed chunked generation

A 14-day itinerary is a large JSON structure. One Gemini request risks token limits and timeouts. So long trips are split into sequential chunks — a few days at a time — each validated against a Zod schema before moving to the next.

For reliability, three Gemini API keys rotate on retryable errors (429, 500, 502). One thing I got right: invalid JSON responses don't trigger key rotation. That's a content problem, not an API problem. Rotating keys on bad output just wastes quota.

PDF export — why I didn't use a library

I tried a few HTML-to-PDF libraries. The output was consistently broken — fonts missing, layouts collapsed. Most of them don't run a real browser engine, so anything depending on computed styles or custom properties breaks.

The fix was Playwright with real Chromium. The API route launches it headlessly, navigates to the export preview page, and captures it as A4. The preview page and the PDF are the same template — what you see is exactly what gets downloaded.

The free-tier wall

Kartografer runs on Gemini's free tier. Multi-key rotation helps with per-minute limits but not daily caps. At any real traffic volume, it runs out fast — and I don't have the budget to fix this with money right now.

So I've been thinking about working around it with design:

• Cache common itineraries — Paris 7-day budget trips don't need fresh generation every time
• Use Explore as a seed — adapt an existing published itinerary instead of generating from scratch
• Async queue — smooth out burst traffic instead of failing mid-request
• BYOK — let users connect their own Gemini key for unlimited personal generation

None of these are built yet. But a hard resource constraint forces you to think about AI differently — not as an unlimited utility, but as something to use carefully.

What I'd do differently

Define the AI proposal schema first. I built the chat feature before locking down what a proposal looked like. That meant refactoring the chat action later to remove direct itinerary mutations. Starting with the schema would have made the whole integration cleaner.

The full source is on GitHub. Live at kartografer.com.