# Travel Planning - Multi-User Travel Itinerary Management System

A comprehensive travel planning application that enables collaborative itinerary planning, expense tracking, and photo sharing for travel groups.

## Features

- **Tour Management**: Create and manage travel tours with multiple legs (stages) and locations
- **Multi-user Collaboration**: Invite friends to join tours with role-based access control
- **Interactive Maps**: Visual tour planning with Leaflet.js integration
- **Expense Tracking**: Automatic cost splitting with configurable adult/child discounts
- **Photo Sharing**: Secure photo album with privacy controls (PUBLIC, TOUR_ONLY, PRIVATE)
- **Real-time Navigation**: Live GPS tracking and route optimization using OSRM API

## Tech Stack

| Layer | Technology | Purpose |
|-------|-----------|---------|
| **Frontend** | React + Vite | Single Page Application with fast HMR |
| | TailwindCSS | Utility-first CSS framework |
| | Zustand | Lightweight state management |
| | Leaflet.js | Interactive map rendering |
| **Backend** | NestJS | Scalable Node.js framework |
| | JWT | Authentication & authorization |
| | Prisma ORM | Type-safe database access |
| | PostgreSQL + PostGIS | Spatial database for geographic data |

## Project Structure

```
travelplanning/
├── backend/                    # Backend API server
│   ├── src/
│   │   ├── auth/              # Authentication modules
│   │   ├── main.ts            # NestJS entry point
│   │   └── v1/              # API v1 endpoints
│   └── prisma/
│       └── schema.prisma      # Database schema
├── frontend/                   # React frontend
│   └── src/
│       ├── pages/            # Main pages
│       ├── components/       # Reusable UI components
│       ├── hooks/          # Custom React hooks
│       └── store/          # Zustand stores
├── docs/                      # Documentation
│   ├── ARCHITECTURE.md        # System architecture
│   └── UITourDesign.md        # UI design specifications
└── .env                       # Environment variables
```

## Database Schema

The application uses PostgreSQL with Prisma ORM. Key models include:

- **User**: Registered users with admin capability
- **Tour**: Travel itineraries with date ranges and participant management
- **Leg**: Stages within a tour (ordered sequence)
- **Location**: Geographic points with timing and status tracking
- **Expense**: Cost tracking linked to legs/locations
- **Photo**: Media storage with privacy controls
- **TourParticipant**: Many-to-many relationship with role-based permissions

### User Roles

| Role | Permissions |
|------|-------------|
| OWNER | Full access to all features |
| MANAGER | Can edit tour content and manage members |
| MEMBER | View tour and participate, access financial data |
| MEMBER_NO_FINANCE | View tour only, no financial access |
| VIEWER_ONLY | Read-only access to itinerary and photos |

## API Endpoints

### Tours
- `GET /api/v1/tours` - Get all public tours
- `POST /api/v1/tours` - Create new tour
- `GET /api/v1/tours/:id` - Get tour details
- `PUT /api/v1/tours/:id` - Update tour

### Authentication
- `POST /api/v1/auth/login` - User login
- `POST /api/v1/auth/register` - User registration
- `POST /api/v1/auth/promote-admin` - Admin role promotion (with secret key)

### Photos
- `GET /api/v1/public-photos` - Get public photos
- `POST /api/v1/tours/:id/photos` - Upload tour photos

## Quick Start

### Prerequisites
- Node.js 18+
- PostgreSQL with PostGIS extension

### Installation

```bash
# Install dependencies
npm install
cd frontend && npm install
cd ../backend && npm install

# Set up database
npx prisma migrate dev
npx prisma generate

# Start development servers
npm run dev                    # Frontend (Vite)
npm run start:backend          # Backend (NestJS)
```

### Environment Variables

Create `.env` in the root directory:

```env
DATABASE_URL="postgresql://user:password@localhost:5432/traveldb"
JWT_SECRET="your-secret-key"
```

## Mobile Optimization

The application is built mobile-first with support for:
- Safe area insets for notch displays (iOS/Android)
- Touch gestures for map interactions
- Responsive layouts for all screen sizes
- Device orientation and compass integration

## Documentation

See the `docs/` directory for detailed documentation:
- [ARCHITECTURE.md](docs/ARCHITECTURE.md) - System architecture and data models
- [UITourDesign.md](docs/UITourDesign.md) - UI design specifications