# 🏔️ Zurich Connect

A modern tour booking platform connecting local guides with explorers in Zurich, Switzerland.

---

## 🚀 Quick Links

### 📖 **New to this project? Start here:**
👉 **[START_HERE.md](./START_HERE.md)** - Your complete guide to getting started

### 🔧 **Ready to deploy?**
Choose your preferred guide:
- 📖 **[DEPLOYMENT_GUIDE.md](./DEPLOYMENT_GUIDE.md)** - Comprehensive tutorial

### 📚 **All Documentation:**
See **[DOCUMENTATION_INDEX.md](./DOCUMENTATION_INDEX.md)** for a complete list of guides

---

## ✨ Features

- 🎫 **Tour Booking System** - Browse, search, and book unique tours
- 👥 **Dual User Roles** - Separate experiences for Guides and Explorers
- 📸 **Image Management** - Upload tour photos and profile pictures to AWS S3
- 🗺️ **Interactive Maps** - View tour locations and meeting points with Mapbox
- ⭐ **Reviews & Ratings** - Rate and review completed tours
- 📧 **Email Notifications** - Booking confirmations and updates via Resend
- 📊 **Dashboards** - Manage tours, bookings, and view statistics
- 🔐 **Secure Authentication** - User registration and login with Better Auth
- 📱 **Responsive Design** - Works beautifully on mobile and desktop

---

## 🛠️ Technology Stack

- **Frontend:** Next.js 16, React 19, TypeScript, Tailwind CSS
- **Backend:** Next.js API Routes, Prisma ORM
- **Database:** PostgreSQL (Neon)
- **File Storage:** AWS S3
- **Authentication:** Better Auth
- **Email:** Resend
- **Maps:** Mapbox
- **Hosting:** Vercel
- **UI Components:** Shadcn UI, Radix UI

---

## 📋 Prerequisites

- Node.js 18+ or 20+
- npm or yarn
- PostgreSQL database (Neon recommended)
- AWS account (for S3)
- Resend account (for emails)
- Mapbox account (for maps)

---

## 🏃‍♂️ Local Development Setup

### 1. Clone the repository

```bash
git clone <repository-url>
cd zurich-connect
```

### 2. Install dependencies

```bash
npm install
```

### 3. Set up environment variables

Copy `.env.example` to `.env` and fill in your credentials:

```bash
cp .env.example .env
```

Required environment variables:
- `DATABASE_URL` - Neon pooled connection
- `DIRECT_DATABASE_URL` - Neon direct connection
- `BETTER_AUTH_SECRET` - Random secret key
- `AWS_BUCKET_NAME` - S3 bucket name
- `AWS_BUCKET_REGION` - S3 region
- `AWS_PUBLIC_ACCESS_KEY` - AWS access key
- `AWS_SECRET_ACCESS_KEY` - AWS secret key
- `NEXT_PUBLIC_MAPBOX_TOKEN` - Mapbox public token
- `RESEND_API_KEY` - Resend API key
- `RESEND_FROM_EMAIL` - Sender email address

See **[QUICK_REFERENCE.md](./QUICK_REFERENCE.md)** for detailed information.

### 4. Run database migrations

```bash
npx prisma migrate deploy
```

### 5. Seed the database (optional)

```bash
npm run seed
```

This creates sample data including:
- 5 tour guides
- 5 explorers
- 6 featured tours
- Tour images
- Sample bookings
- Reviews

### 6. Start the development server

```bash
npm run dev
```

Open [http://localhost:3000](http://localhost:3000) in your browser.

---

## 📦 Production Deployment

### To Vercel (Recommended)

For complete deployment instructions, see:
- **[DEPLOYMENT_GUIDE.md](./DEPLOYMENT_GUIDE.md)** - Full tutorial
- **[VISUAL_DEPLOYMENT_GUIDE.md](./VISUAL_DEPLOYMENT_GUIDE.md)** - Quick checklist

Quick steps:
1. Push code to GitHub
2. Import project in Vercel
3. Add environment variables
4. Deploy!

---

## 🗂️ Project Structure

```
zurich-connect/
├── src/
│   ├── app/                 # Next.js app router pages
│   │   ├── (auth)/         # Authentication pages
│   │   ├── api/            # API routes
│   │   ├── bookings/       # Booking pages
│   │   ├── dashboard/      # User dashboards
│   │   ├── profile/        # Profile pages
│   │   ├── tours/          # Tour pages
│   │   └── users/          # User management
│   ├── components/         # React components
│   │   ├── ui/            # Shadcn UI components
│   │   └── maps/          # Map components
│   ├── lib/               # Utility libraries
│   │   ├── auth.ts        # Authentication config
│   │   ├── db.ts          # Database client
│   │   ├── s3-client.ts   # AWS S3 client
│   │   └── email.ts       # Email service
│   ├── hooks/             # Custom React hooks
│   └── types/             # TypeScript definitions
├── prisma/
│   ├── schema.prisma      # Database schema
│   ├── migrations/        # Database migrations
│   └── seed.ts           # Seed data script
├── public/
│   ├── assets/           # Static assets
│   └── uploads/          # Local uploads (dev only)
└── [documentation files]
```

---

## 🎯 Available Scripts

| Command | Description |
|---------|-------------|
| `npm run dev` | Start development server |
| `npm run build` | Build for production |
| `npm start` | Start production server |
| `npm run lint` | Run ESLint |
| `npm run seed` | Seed database with sample data |
| `npx prisma studio` | Open Prisma Studio (database GUI) |
| `npx prisma migrate deploy` | Run database migrations |

---

## 🔐 Security

- ✅ Environment variables for sensitive data
- ✅ Secure authentication with Better Auth
- ✅ Password hashing with bcrypt
- ✅ SQL injection prevention with Prisma
- ✅ CORS configured for S3
- ✅ HTTPS enforced on Vercel
- ✅ Input validation with Zod

**Never commit `.env` files to version control!**

---

## 📚 Documentation

| Document | Description |
|----------|-------------|
| [START_HERE.md](./START_HERE.md) | Main navigation guide |
| [DEPLOYMENT_GUIDE.md](./DEPLOYMENT_GUIDE.md) | Complete deployment tutorial |
| [VISUAL_DEPLOYMENT_GUIDE.md](./VISUAL_DEPLOYMENT_GUIDE.md) | Quick deployment checklist |
| [TROUBLESHOOTING_GUIDE.md](./TROUBLESHOOTING_GUIDE.md) | Common issues and solutions |
| [QUICK_REFERENCE.md](./QUICK_REFERENCE.md) | Environment variables reference |
| [DEPLOYMENT_CHECKLIST.md](./DEPLOYMENT_CHECKLIST.md) | Printable checklist |
| [DOCUMENTATION_INDEX.md](./DOCUMENTATION_INDEX.md) | All documentation files |

---

## 🆘 Getting Help

1. Check [TROUBLESHOOTING_GUIDE.md](./TROUBLESHOOTING_GUIDE.md)
2. Review [DEPLOYMENT_GUIDE.md](./DEPLOYMENT_GUIDE.md)
3. Check browser console for errors (F12)
4. Review Vercel deployment logs
5. Check service status pages

---

## 📝 License

This project is private and proprietary.

---

## 🙏 Acknowledgments

Built with:
- [Next.js](https://nextjs.org/)
- [Prisma](https://www.prisma.io/)
- [Tailwind CSS](https://tailwindcss.com/)
- [Shadcn UI](https://ui.shadcn.com/)
- [Neon](https://neon.tech/)
- [Vercel](https://vercel.com/)
- [AWS S3](https://aws.amazon.com/s3/)
- [Resend](https://resend.com/)
- [Mapbox](https://www.mapbox.com/)

---

**Ready to deploy? Start with [START_HERE.md](./START_HERE.md)! 🚀**
