Pull the repository

Fork, then clone

Fork the repository on GitHub first. A fork is your own copy of it, and Vercel will deploy from your fork later. Then clone your fork:

git clone https://github.com/<your-account>/travole.git
cd travole
bun install

bun install reads bun.lock, so you get the exact versions the app was tested with.

Look around before you change anything

travole/
├── app/                  the routes (Next.js App Router)
│   ├── (auth)/           login, signup, invitation, password reset
│   ├── (app)/            everything behind the login
│   │   ├── dashboard/    summary, finances, the receipt ledger
│   │   ├── trips/        trips, expenses, the Excel and PDF exports
│   │   └── settings/     countries, categories, tax rates, invitations, account
│   └── api/              the auth handler and the receipt download
├── components/tv/        the app's own UI pieces (hero, breakdown, plates, fields)
├── components/ui/        the one shared primitive (button)
├── lib/
│   ├── db/               the Drizzle schema, the migrations and the seed
│   ├── auth/             Better Auth, and the one gate that decides who may sign up
│   ├── queries/          every read the pages make
│   ├── report/           the report's shape, and its Excel and PDF renderers
│   └── storage.ts        receipt upload and download (Cloudflare R2)
├── .brand/               the design tokens and component styles
├── e2e/                  Playwright end-to-end tests
└── .env.example          every variable the app reads, each one explained

Run the tests first

The unit tests need no database and no network:

bun run test

If they are green, your checkout is sound, and any later failure is in your configuration, not in the code. That single fact will save you an hour in step 6.

Copy the environment file

cp .env.example .env

Do not fill it in yet. The next steps explain every variable, and the step after that creates the services that give you their values.