Travel Pin Board 🌍

A personal map-based travel planning application where you can save places you love, places you want to visit, and get AI-powered travel recommendations.

Features ✨

• Interactive Maps - Visualize your travel plans with Leaflet + OpenStreetMap integration
• Trip Organization - Create and manage multiple trips with custom themes and date ranges
• Smart Tagging - Organize places with flexible custom tags (Favorites, Want to Go, or custom categories)
• AI Travel Assistant - Get personalized recommendations based on your saved places using OpenAI GPT-4o
• Place Management - Add places by searching or clicking on the map with reverse geocoding
• Trip Sharing - Generate public share links for your trips with customizable tag filtering
• Dark Mode - Beautiful light and dark themes
• Responsive Design - Works great on desktop and mobile

Tech Stack 🛠️

Frontend

• React 18 with TypeScript
• Vite for fast development and building
• TailwindCSS for styling
• shadcn/ui for beautiful, accessible components
• Leaflet + OpenStreetMap for maps (free alternative to Google Maps)
• TanStack Query for server state management
• Wouter for lightweight routing

Backend

• Express.js with TypeScript
• SQLite database with Drizzle ORM
• Session-based authentication (mock auth for development)
• OpenAI API for AI travel recommendations
• Nominatim API for place search and geocoding

Quick Start 🚀

Prerequisites

• Node.js 18+
• npm or yarn

Installation

1. Navigate to the project directory

   cd TravelPinBoard

2. Install dependencies

   npm install

3. Set up environment variables (optional) Create a .env file in the root directory:

   # Optional - for AI chat features
   OPENAI_API_KEY=your_openai_api_key_here
   
   # Optional - session secret (defaults to dev secret)
   SESSION_SECRET=your_session_secret_here

4. Initialize the database

   npm run db:push

5. Start the development server

   npm run dev

6. Open your browser Visit http://localhost:3000 and start planning your travels!

Usage Guide 📖

Getting Started

1. Visit http://localhost:3000
2. Click "Start Your Journey" to automatically log in (development mode)
3. Create your first trip by clicking "Create Trip"

Managing Trips

• Create Trip: Set a name, description, date range, and color theme
• Edit Trip: Update trip details anytime
• Delete Trip: Remove trips you no longer need

Adding Places

• Search: Use the search bar to find places by name
• Map Click: Click anywhere on the map to add a place at that location
• Tagging: Assign places to tags like "Favorites", "Want to Go", or create custom tags

AI Travel Assistant

• Open the chat panel on the right
• Ask questions about your travel plans
• Get personalized recommendations based on your saved places
• The AI considers your preferences and trip context

Sharing Trips

• Click the share button on any trip
• Choose which tags to include in the share
• Generate a public link that others can view (no login required)

Scripts 📝

# Development
npm run dev          # Start development server

# Database
npm run db:push      # Push schema changes to database

# Building
npm run build        # Build for production
npm run start        # Start production server

# Type Checking
npm run check        # Run TypeScript type checking

Project Structure 📁

TravelPinBoard/
├── client/                 # Frontend React application
│   ├── src/
│   │   ├── components/     # Reusable UI components
│   │   ├── hooks/         # Custom React hooks
│   │   ├── pages/         # Page components
│   │   └── lib/           # Utilities and configurations
├── server/                # Backend Express application
│   ├── services/          # External service integrations
│   ├── db.ts             # Database connection
│   ├── routes.ts         # API routes
│   ├── storage.ts        # Data access layer
│   └── mockAuth.ts       # Authentication system
├── shared/               # Shared types and schemas
└── dev.db               # SQLite database file

API Endpoints 🔌

Authentication

• GET /api/login - Login (auto-login in development)
• GET /api/logout - Logout
• GET /api/auth/user - Get current user

Trips

• GET /api/trips - Get user's trips
• POST /api/trips - Create new trip
• GET /api/trips/:id - Get trip with places
• PATCH /api/trips/:id - Update trip
• DELETE /api/trips/:id - Delete trip

Places

• GET /api/places - Get places (with optional tripId filter)
• POST /api/places - Create new place
• PATCH /api/places/:id - Update place
• DELETE /api/places/:id - Delete place
• GET /api/places/search - Search places via Nominatim

Tags

• GET /api/tags - Get tags for a trip
• POST /api/tags - Create new tag
• PATCH /api/tags/:id - Update tag
• DELETE /api/tags/:id - Delete tag

Chat (AI Assistant)

• GET /api/chat/messages - Get chat history
• POST /api/chat/message - Send message to AI
• DELETE /api/chat/messages - Clear chat history

Sharing

• POST /api/trips/:tripId/shares - Create share link
• GET /api/trips/:tripId/shares - Get share links for trip
• GET /api/public/share/:token - View shared trip (public)

Development Notes 🔧

Database

• Uses SQLite for local development (file: dev.db)
• Database schema is managed with Drizzle ORM
• Run npm run db:push after schema changes

Authentication

• Currently uses a mock authentication system for development
• Automatically creates a demo user when you visit /api/login
• Sessions are stored in memory (will reset on server restart)

Maps

• Uses Leaflet with OpenStreetMap tiles (free alternative to Google Maps)
• Place search powered by Nominatim API (respects rate limits)
• Supports both place search and reverse geocoding

AI Features

• Requires OpenAI API key for chat functionality
• Falls back gracefully if API key is not provided
• Chat history is stored per user in the database

Contributing 🤝

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Support 💬

If you have any questions or run into issues, please open an issue on GitHub.

---

Happy travels! 🧳✈️