<div align="center">

# Trovo

### Discover. Plan. Go.

**AI-powered travel planning & booking SaaS** — an AI itinerary generator, a
multi-vendor tour marketplace, subscription billing, and a full admin panel in
one Next.js app.

[Live demo](#demo-credentials) · [Quick start](#quick-start) · [Documentation](#documentation)

</div>

---

Trovo is a production-ready travel platform by **DevSnack**. Deploy it as a
consumer trip planner, a tour marketplace, a white-label travel SaaS — or all
three at once.

## Features

**AI trip planning**
- Day-by-day itinerary generation (streaming) from a destination, dates, budget, and interests
- Provider-switchable AI — OpenAI GPT-4o or Google Gemini 1.5 Pro, toggled from the admin panel
- Per-day refinement, packing lists, weather (Open-Meteo), and Google Maps with plotted stops
- PDF export of any itinerary (Puppeteer)

**Tour marketplace**
- Multi-vendor listings with photos, availability, and reviews
- Provider portal — listings, bookings, payouts, profile, reviews
- Stripe + PayPal checkout with platform commission split
- Wishlist, search, and per-destination guide pages (AI-generated, cached)

**Billing & monetization**
- Subscription plans (Free / Pro / Business) via Stripe and PayPal — monthly, yearly, lifetime
- Plan feature gates, per-user AI rate limiting, affiliate links (Booking.com / Skyscanner / GetYourGuide)
- Embeddable trip widget for buyers' own sites

**Admin & ops**
- Full admin panel — users, listings, bookings, billing, settings, content
- Encrypted-at-rest AI keys, role-based access (Admin / Moderator / Provider / User)
- Newsletter campaigns with open/click tracking, email templates (React Email + Resend)

**Collaboration**
- Real-time trip collaboration with live presence (SSE), activity comments, and edit-notify emails
- Viewer / Editor collaborator roles

## Tech stack

| Layer | Choice |
| ----- | ------ |
| Framework | Next.js 16 (App Router, SSR) |
| Language | TypeScript (strict) |
| Styling | Tailwind CSS v4 + shadcn/ui |
| Auth | NextAuth v5 (Google OAuth + credentials) |
| ORM / DB | Prisma + PostgreSQL (Neon) |
| AI | Vercel AI SDK → OpenAI GPT-4o + Google Gemini 1.5 Pro |
| Maps | Google Maps (`@vis.gl/react-google-maps`) |
| Weather | Open-Meteo (free, no key) |
| Payments | Stripe + PayPal |
| Images | Cloudflare R2 + sharp (WebP variants) |
| Email | Resend + React Email |
| Realtime | SSE (trip collaboration) |
| PDF | Puppeteer |
| Testing | Vitest + Testing Library + Playwright |
| Deploy | Vercel |
| Package manager | **pnpm** |

## Quick start

**Prerequisites:** Node.js 20+, [pnpm](https://pnpm.io), and a PostgreSQL database
(a free [Neon](https://neon.tech) branch works great).

```bash
# 1. Install dependencies
pnpm install

# 2. Configure environment
cp .env.example .env.local
#    then fill in the values (see "Environment variables" below)

# 3. Set up the database
pnpm db:migrate      # create + apply the schema

# 4. Run the dev server
pnpm dev
```

Open <http://localhost:3000>.

## Environment variables

All env vars are declared and validated with Zod in [`lib/env.ts`](lib/env.ts).
Start from [`.env.example`](.env.example), which mirrors that schema and includes
inline setup notes for each integration.

**Required** (the app won't boot without them):

| Var | Purpose |
| --- | ------- |
| `DATABASE_URL` | PostgreSQL connection string |
| `AUTH_SECRET` | NextAuth session secret (≥16 chars; `openssl rand -base64 32`) |
| `ENCRYPTION_KEY` | AES-256 key for encrypting AI keys at rest (**exactly 64 hex chars**) |

**Recommended for full functionality** (each is optional and degrades
gracefully when absent): `OPENAI_API_KEY` *or* `GOOGLE_AI_API_KEY` (AI planning),
`NEXT_PUBLIC_GOOGLE_MAPS_API_KEY` + `GOOGLE_MAPS_API_KEY` (maps & geocoding),
`STRIPE_*` and `PAYPAL_*` (payments & subscriptions), `R2_*` (image uploads),
`RESEND_API_KEY` (email), `GOOGLE_CLIENT_ID/SECRET` (Google sign-in).

PayPal subscription Plan IDs have no dashboard UI — run `pnpm paypal:setup` to
create them via the API. See [`docs/STRIPE.md`](docs/STRIPE.md) for payment setup.

## Demo credentials

The hosted demo is pre-populated. Sign in with:

| Role | Email | Password |
| ---- | ----- | -------- |
| Admin | `admin@trovo.app` | `admin123` |
| Provider | `provider@trovo.app` | `provider123` |
| User | `user@trovo.app` | `user123` |

## Project structure

```
app/          Next.js App Router — public pages, dashboard, admin, provider, API
components/   shadcn/ui-based UI components
lib/          Shared utilities & service clients (ai, plans, auth, paypal, …)
prisma/       schema.prisma + migrations
emails/       React Email templates
docs/         PRD, launch guide, Stripe & deploy playbooks
e2e/          Playwright end-to-end tests
proxy.ts      Route protection (Next 16's renamed middleware)
```

`lib/` and `components/` have their own `README.md` inventories. Route
protection lives in [`proxy.ts`](proxy.ts): `/dashboard/*` requires auth,
`/provider/*` requires a verified provider, `/admin/*` requires admin/moderator.

## Scripts

| Command | Description |
| ------- | ----------- |
| `pnpm dev` | Dev server (Turbopack) |
| `pnpm build` | Production build (zero-warning) |
| `pnpm lint` | ESLint |
| `pnpm format` | Prettier write |
| `pnpm test` | Vitest unit/integration suite |
| `pnpm test:coverage` | Vitest with coverage |
| `pnpm e2e` | Playwright end-to-end tests |
| `pnpm db:migrate` | Create + apply a migration |
| `pnpm db:studio` | Inspect the database |
| `pnpm email:dev` | Preview React Email templates |
| `pnpm paypal:setup` | Create PayPal subscription products + plans |

## Testing

- **Unit / integration:** Vitest + Testing Library — `pnpm test`
- **End-to-end:** Playwright (auto-starts the dev server) — `pnpm e2e`

## Deployment

Trovo is built for [Vercel](https://vercel.com). The full production playbook —
required env vars, credential rotation, payment go-live, and post-deploy webhook
setup — is in [`docs/DEPLOY.md`](docs/DEPLOY.md).

## Documentation

| Doc | What's in it |
| --- | ------------ |
| [`docs/PRD.md`](docs/PRD.md) | Product requirements — modules, schema, AI prompts, env vars, seed data |
| [`docs/LAUNCH.md`](docs/LAUNCH.md) | Launch guide — demo, landing, docs, code quality, build order |
| [`docs/STRIPE.md`](docs/STRIPE.md) | Stripe & PayPal payment setup |
| [`docs/DEPLOY.md`](docs/DEPLOY.md) | Vercel production deploy playbook |

## License

Sold under the [CodeCanyon Regular / Extended License](https://codecanyon.net/licenses/standard).
Trovo and the DevSnack brand are © DevSnack. Replace the branding via the admin
panel (white-label) before reselling a deployment.