Claude Code Development Guide

Last Updated: March 11, 2026 Purpose: Rules and workflow for working with this codebase

Starting a New Session

Read these docs in order:

CLAUDE.md (this file) — Rules & workflow
docs/product_brief.md — Source of truth for what we're building
CURRENT_STATE.md — What's built and how it fits together
NOW.md — What to work on next
git log --oneline -10 — Recent commits

Optional (if relevant to task):

docs/ios-v2-plan.md — iOS v2 plan + implementation tracker (3 pillars, progress tables, decisions log)
docs/city-intelligence.md — City intelligence pipeline (Stage 0): the IP layer that makes TourGraph unique
docs/six-degrees-chains.md — Chain generation (Stages 1+2): pair selection, quality standards, gallery UX
docs/data-snapshot.md — Data baseline stats (4-layer IP asset, 136K tours)
docs/data-schema.md — Full SQL schema (CREATE TABLE statements for all 7 tables)
data/scripts/README.md — Data pipeline playbook (step-by-step rebuild from scratch)
docs/implementation/ios-app-store.md — App Store submission metadata, signing info, pre-submission checklist
docs/implementation/ios-architecture.md — iOS app design: seed DB (120MB), per-tour enrichment, column analysis, GRDB safety, services, navigation
docs/reference/thesis_validation.md — Why the original thesis was killed (context only)
archive/docs/api_landscape.md — Viator API details, test results, response formats
Before beginning implementation, check with your project lead for any cross-session context or coordination notes that may affect this work.

Project Context

TourGraph was originally supply-side infrastructure for tour operators (AI extraction + MCP server). That thesis was invalidated in February 2026 — Peek, TourRadar, Magpie, and Expedia all shipped live MCP servers. Rather than kill the project ($200 invested, Viator API working), we pivoted to something radically different:

TourGraph.ai is a zero-friction consumer site and iOS app that makes people smile using the world's tour data.

Not a booking engine. Not a travel planner. Not a recommendation engine. A place you visit because it's fun, surprising, and shareable.

Full product vision: docs/product_brief.md Why we pivoted: docs/reference/thesis_validation.md

The Four Pillars

Every feature, design decision, and code commit must pass all four tests. If it doesn't, it's out of scope.

1. Zero Friction

No signup, no login, no personal data, no cookies beyond essential function. A stranger lands on the site and is delighted within 5 seconds.

Test: Can my mom use this without asking me a single question?

2. Instant Smile

Every interaction should brighten someone's day. Warm, witty, wonder-filled — never snarky, cynical, or mean. The goal is "oh wow, I didn't know that existed."

Test: Would I text this to a friend just because it made me smile?

3. Effortlessly Shareable

Every piece of content has a unique URL and a beautiful Open Graph preview card. The viral loop is: see something delightful -> share it -> friend clicks -> friend is delighted -> friend shares.

Test: Does the link preview on iMessage/WhatsApp/Twitter look good enough to tap?

4. Rabbit Hole Energy

That "one more click" quality through genuine curiosity, not dark patterns. Wikipedia-style: you came for one thing, 20 minutes later you're somewhere unexpected and loving it.

Test: Did I just spend 10 minutes when I meant to spend 30 seconds?

What We're Building

Four features, all shipping before launch. Website first, then iOS app.

Feature 1: Tour Roulette (Core Loop)

One big button. Press it. Get a random tour from somewhere in the world — weighted toward extremes (highest rated, weirdest, most expensive, cheapest). Photo, title, destination, price, rating, and an AI-generated witty one-liner. Press again.

Feature 2: Right Now Somewhere...

Time-zone-aware: shows a tour happening (or about to happen) where it's currently a beautiful time of day. "Right now in Kyoto it's 6:47am and you could be doing forest bathing with a Buddhist monk. 4.9 stars."

Feature 3: The World's Most ___

Daily superlatives from the Viator catalog. Most expensive tour. Cheapest 5-star experience. Longest duration. Each one is a shareable card with photo, stat, and witty caption.

Feature 4: Six Degrees of Anywhere

Pre-generated chains of tours connecting cities through surprising thematic links — shared activities, cultural connections, overlapping cuisines, historical threads. 491 chains, each 5 stops long. Presented as chain roulette: one random chain with full vertical timeline, "Surprise Me" to load another.

What We're NOT Building

A booking engine (Viator affiliate links handle bookings)
A travel planning tool (no itineraries, no trip builders)
A review aggregator
A social network (no profiles, no followers)
A recommendation engine (no "based on your history" — it's random, serendipitous)
Anything that requires user accounts or personal data

Build Order

Phase	What	Platform	Timeframe
1	Tour Roulette	Web	Week 1
2	Right Now Somewhere	Web	Week 1-2
3	The World's Most ___	Web	Week 2
4	Six Degrees of Anywhere	Web	Week 2-3
5	Polish, OG cards, sharing	Web	Week 3
6	Launch website	Web	Week 3
7	iOS app (all 4 features)	iOS/SwiftUI	Week 4-5
8	App Store submission	iOS	Week 5-6

Timeframes are estimates, not commitments. This is supposed to be fun.

Critical Rules

Non-Negotiables

Unauthorized commits — NEVER commit without explicit approval
Over-engineering — KISS always. Ship simple, iterate fast.
Pillar violations — Every feature/decision must pass all four pillar tests
Not reading the product brief — docs/product_brief.md is the source of truth
Scope creep — If it's not one of the four features, it's not in scope
Guessing — Say "I don't know" if unsure
Dark patterns — No engagement tricks, no manipulative UX, no data harvesting
Premature abstraction — Don't build frameworks. Build features that work.

How to Be a True Partner

Pillar check first — Does this pass all four tests?
Fun matters — If the code isn't fun to build, something's wrong
One feature at a time — Complete, review, then proceed
KISS principle — Simple > clever
Explicit permission — Get approval before every commit
Challenge bad ideas — Don't just agree
Think sharing — Every piece of content needs a URL and OG card

Tech Stack

Website

Component	Choice	Rationale
Backend API	Express 5 + TypeScript	Standalone API server, clean separation from frontend
Frontend	Next.js 16 (React)	SSR for OG previews, pure API consumer
Hosting	DigitalOcean droplet (~$6/mo)	PM2 runs both processes, nginx routes traffic
Data	Viator Partner API (Basic tier, free)	Already integrated, 300K+ experiences
AI Layer	Claude API	Witty captions, Six Degrees chains (pipeline only)
Database	SQLite (read-only from backend)	Pre-built local index, no API calls at request time
Domain	tourgraph.ai	Already owned and configured

iOS App

Component	Choice	Rationale
Framework	SwiftUI	Already proven with GitaVani
Architecture	Bundled SQLite DB + lazy enrichment	All features work offline, enrichment adds full data on demand
Data	GRDB.swift + bundled tourgraph.db (120MB)	Read-write queries (read for features, write for enrichment)
Enrichment	tourgraph.ai server	Full descriptions + photo galleries fetched per-tour on detail tap
Local Storage	UserDefaults	Favorites, settings persistence

Architecture

                    ┌──────────────────┐
                    │   tourgraph.ai   │  (DigitalOcean droplet)
                    └────────┬─────────┘
                             │ Nginx
                    ┌────────┴─────────┐
                    ▼                  ▼
           ┌──────────────┐   ┌──────────────┐
           │ backend/     │   │ web/         │
           │ Express API  │   │ Next.js      │
           │ :3001        │   │ :3000        │
           │ /api/v1/*    │   │ /* (pages)   │
           └──────┬───────┘   └──────────────┘
                  │ read-only         │ fetch()
                  ▼                   │
           ┌──────────────┐           │
           │ data/        │◄──────────┘
           │ tourgraph.db │   (web calls backend API,
           │ (SQLite)     │    never touches DB directly)
           └──────────────┘

  data/scripts/ ──── pipeline (Viator, Claude) ──── writes to DB

User flow: Visit site -> See delightful content -> Share link -> Friend visits -> Repeat

No user accounts. No databases of personal data. Just cached Viator responses + AI-generated captions.

Data We Have (Viator Basic Tier)

Product search by destination & category
Product details: title, description, highlights
Photos: 10-31 CDN-hosted images per product
Pricing: by age band (adult/child/infant/senior)
Ratings: star rating + review count (not review text at Basic)
Duration, schedule, operating hours
Categories and tags
Location/meeting points with lat/long
Attraction associations
300,000+ experiences across 3,380+ destinations

Upgrade path (Full tier, also free, requires certification): Adds review text, real-time availability, and bulk catalog ingestion.

Design Principles

Dark mode default — feels premium, photos pop
Big photos — tour images do the heavy lifting
Minimal UI — the content is the interface
Fast — every interaction feels instant (pre-fetch, cache, skeleton loaders)
Mobile-first — most sharing happens on phones
Playful typography — not corporate, not childish, just warm

Environment Setup

Backend API:

cd backend
npm install
npm run dev     # Express on :3001

Web Frontend:

cd web
npm install
npm run dev     # Next.js on :3000 (requires backend running)

Data Pipeline:

cd data
npm install
npx tsx scripts/1-viator/indexer.ts --full   # example

API Keys (in .env.local at repo root or in respective directories):

VIATOR_API_KEY — https://viator.com/partners (Basic Access, free affiliate signup)
ANTHROPIC_API_KEY — https://console.anthropic.com
DATABASE_PATH — path to SQLite DB (defaults to data/tourgraph.db)

Development Standards

Code Quality

TypeScript for all code — strict mode, proper types (backend, web, data pipeline)
React Server Components where possible — minimize client JS
Web never touches DB — all data access goes through backend API
OG image generation — every shareable page needs proper meta tags

Git Workflow

Atomic commits — One logical change per commit
Clear messages — Descriptive, explain the why
NO attribution — Never include "Generated with Claude"
Working state — Every commit leaves the site functional

Core Principles

Ship fast, iterate — Working feature > perfect feature
Cache aggressively — Viator API has rate limits; cache everything
Mobile-first — Design for phones, enhance for desktop
Share-first — OG cards and unique URLs are not afterthoughts

Documentation Structure

Root Level:

CLAUDE.md — Rules & workflow (this file)
README.md — Project overview
NOW.md — Current priorities (forward-looking only)
CURRENT_STATE.md — What's built & status
CHANGELOG.md — Version history

Core Docs (docs/):

docs/product_brief.md — Product vision (source of truth)
docs/ux_design.md — UX design: wireframes, principles, interaction flows
docs/city-intelligence.md — City intelligence pipeline (Stage 0) — the IP layer
docs/six-degrees-chains.md — Chain generation (Stages 1+2) — pair selection, quality, gallery
docs/data-snapshot.md — Data baseline (4-layer IP asset, 136K tours)
docs/data-schema.md — Full SQL schema (7 tables including city_readings)
docs/architecture.md — Technical architecture, schema, indexer design

Implementation Docs (docs/implementation/):

docs/implementation/implementation_plan.md — Phase 1-3 build plan
docs/implementation/ios-architecture.md — iOS app design: seed DB (120MB), per-tour enrichment, column analysis, GRDB safety, services, navigation
docs/implementation/ios-app-store.md — App Store submission metadata, signing, checklist

Reference Docs (docs/reference/):

docs/reference/viator-api-reference.md — Basic-tier API endpoint summary
docs/reference/viator-openapi.json — OpenAPI spec for Viator
docs/reference/rate-limiting.md — Viator rate limiting details
docs/reference/phase4-six-degrees.md — Early Six Degrees research & UI spec
docs/reference/thesis_validation.md — Competitive analysis that killed original thesis

Data Pipeline (data/):

data/scripts/README.md — Pipeline playbook (step-by-step rebuild guide)
data/scripts/1-viator/ — Viator API indexing (destinations, tours, dev data)
data/scripts/2-oneliners/ — AI caption generation (Claude Haiku 4.5)
data/scripts/3-city-intel/ — City intelligence (readings → profiles merge pipeline)
data/scripts/4-chains/ — Six Degrees chain generation
data/scripts/5-trivia/ — Trivia pool generation (SQL generators + Haiku fakes)
data/scripts/utils/ — Database audit tools
data/lib/ — Shared library (db.ts, viator.ts, claude.ts, city-intel.ts, types.ts)

Archive (Phase 0 — reference only):

archive/scripts/ — Extraction & Viator API scripts (API patterns reusable)
archive/results/ — 7 operators, 83 products, scorecards
archive/docs/ — Old strategy docs, MkDocs site content, API landscape
archive/schemas/ — OCTO extraction schema
archive/prompts/ — Domain-specific extraction prompts
archive/CHANGELOG.md — Phase 0 version history

Reusable Assets from Phase 0

Asset	Location	What's Reusable
Viator API patterns	`archive/scripts/viator_compare.py`	Endpoint URLs, auth headers, response parsing, product search, detail fetching
Working API key	`.env` / `.env.local`	`VIATOR_API_KEY` (production, Basic tier)
Domain	tourgraph.ai	DNS configured, pointing to DigitalOcean droplet

Key Concepts

Viator Partner API — Our primary data source. 300K+ experiences, free Basic tier. We're affiliates — bookings redirect to Viator and we earn commission.
OG Cards — Open Graph meta tags that create rich previews when links are shared on social platforms. Critical for Pillar 3 (Effortlessly Shareable).
Tour Roulette — The core engagement loop. Random tour discovery, weighted toward interesting extremes.
Six Degrees — The graph feature. 491 pre-generated chains connecting cities through thematic links. Chain roulette shows one random chain with full timeline, "Surprise Me" loads another.

Success Metrics (Vibes, Not KPIs)

Friends texting each other TourGraph links
Someone at a dinner party saying "have you seen this site?"
A Reddit post titled "I just lost an hour on this weird tour website"
The app becoming someone's "bored in line" go-to
The developer having fun building it

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Claude Code Development Guide

Last Updated: March 11, 2026 Purpose: Rules and workflow for working with this codebase

Starting a New Session

Project Context

The Four Pillars

1. Zero Friction

2. Instant Smile

3. Effortlessly Shareable

4. Rabbit Hole Energy

What We're Building

Feature 1: Tour Roulette (Core Loop)

Feature 2: Right Now Somewhere...

Feature 3: The World's Most ___

Feature 4: Six Degrees of Anywhere

What We're NOT Building

Build Order

Critical Rules

Non-Negotiables

How to Be a True Partner

Tech Stack

Website

iOS App

Architecture

Data We Have (Viator Basic Tier)

Design Principles

Environment Setup

Development Standards

Code Quality

Git Workflow

Core Principles

Documentation Structure

Reusable Assets from Phase 0

Key Concepts

Success Metrics (Vibes, Not KPIs)

FilesExpand file tree

CLAUDE.md

Latest commit

History

CLAUDE.md

File metadata and controls

Claude Code Development Guide

Last Updated: March 11, 2026 Purpose: Rules and workflow for working with this codebase

Starting a New Session

Project Context

The Four Pillars

1. Zero Friction

2. Instant Smile

3. Effortlessly Shareable

4. Rabbit Hole Energy

What We're Building

Feature 1: Tour Roulette (Core Loop)

Feature 2: Right Now Somewhere...

Feature 3: The World's Most ___

Feature 4: Six Degrees of Anywhere

What We're NOT Building

Build Order

Critical Rules

Non-Negotiables

How to Be a True Partner

Tech Stack

Website

iOS App

Architecture

Data We Have (Viator Basic Tier)

Design Principles

Environment Setup

Development Standards

Code Quality

Git Workflow

Core Principles

Documentation Structure

Reusable Assets from Phase 0

Key Concepts

Success Metrics (Vibes, Not KPIs)