133 lines
4.5 KiB
Markdown
133 lines
4.5 KiB
Markdown
# 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 |