TripPlanner

A full-stack trip-planning app: travelers build day-by-day itineraries from a shared, crowdsourced attraction database, schedule them on a per-day calendar (including flights, accommodation stays, and free-form time slots), track a multi-currency budget, and collaborate on a trip with other users.

Live app: https://trip-planner-beta-dusky.vercel.app/ API docs: /api-docs (Swagger UI) — see also swagger.yaml

See also: SPEC.md (system spec, ERD, full endpoint table), PRD.md (product requirements), DESIGN.md, FLOWS.md, WIREFRAMES.md, PRESENTATION.md.

---

What it does

TripPlanner is built around one idea: attractions are global, shared, crowdsourced objects (name, location, category, "mood" tags), while trips are where an attraction gets a schedule (planned date/time, duration, and — for residences — trip-specific stay dates and price). The same museum can be linked into many different users' trips without duplicating its data; only the per-trip scheduling is trip-specific.

Core features:

• Trip management — create/edit/delete trips (destination, dates, budget/currency, cover image, "mood" tags, privacy), with owner + collaborator access control.
• Attraction discovery — search/browse a shared attraction database by country, city, or category; add existing attractions to a trip or create new ones inline.
• Calendar scheduling — a day-by-day calendar view (CalendarSection) that places attractions, flights, and free-form time slots on a timeline, including overnight-spanning blocks (e.g. a hotel stay or overnight flight) and an auto-fit day window.
• Flights & residences as trip-scoped schedule entries — flights and ad-hoc "free time" slots exist only inside a trip's schedule (no shared document); residences keep only reusable place data (name, location, type) on the shared Attraction document, while stay dates/price/notes live on the trip's schedule entry so the same residence can be reused across trips with different dates each time.
• Collaboration — trip owners invite collaborators by email; collaborators can view/edit the itinerary, only the owner can manage collaborators or delete the trip.
• Explore — browse public trips other users have shared, for inspiration.
• Analytics — personal and global stats (attraction category distribution, mood breakdown, etc.) on the /analytics page.
• Admin — manage the shared taxonomy (attraction types, categories, mood tags) at /admin, restricted to users with role: "admin".

How it's built

Next.js 16 (App Router) serves as both frontend and backend — there is no separate Node server. Pages under src/app/** are the frontend; route handlers under src/app/api/** are the REST API, backed by MongoDB via Mongoose. See PRESENTATION.md for the full architecture writeup.

• Frontend: React 19, CSS Modules (no Tailwind/component library — see DESIGN.md), Context API for auth/attraction-taxonomy state, Leaflet for maps.
• Backend: Next.js Route Handlers, organized by domain (api/trips, api/attractions, api/auth, api/users, api/attraction-types, api/attraction-categories, api/mood-tags, api/analytics, api/explore, plus api/geo and api/route proxies for map boundary/routing lookups). Business logic for the two largest domains (trips, attractions) lives in src/lib/services/; every route is wrapped in a shared error-handling/logging/CORS layer (src/lib/withApiHandler.ts).
• Database: MongoDB via Mongoose (src/models/*.ts). See SPEC.md for the full ERD.
• Auth: JWT (jsonwebtoken) + bcrypt-hashed passwords (bcryptjs). Sessions are a 7-day JWT in Authorization: Bearer <token>; there is no server-side session store.

Maps & routing

Map features are built from four external services, proxied through Next.js API routes (api/geo/*, api/route/*) to avoid CORS and to attach required headers (e.g. a custom User-Agent, which these free public instances require):

• Leaflet — client-side map rendering only. It doesn't fetch data itself; it draws whatever the services below hand it (polylines, boundary polygons).
• OpenStreetMap / Nominatim — geocoding and place boundaries. Given a place name, returns its shape as GeoJSON (Polygon/MultiPolygon), used to draw city/country outlines. Proxied via GET /api/geo/city and GET /api/geo/country (src/app/api/geo/{city,country}/route.ts).
• Valhalla — walking/driving routing between two points. Proxied via GET /api/route/valhalla (src/app/api/route/valhalla/route.ts), which actually calls OSRM instances at routing.openstreetmap.de (the public Valhalla demo is unreliable). Returns turn-by-turn geometry and duration.
• Transitous — public transit routing (bus/rail/tram/etc.), an OTP2/MOTIS instance. Proxied via GET /api/route/transit (src/app/api/route/transit/route.ts). Returns itineraries with per-leg transit lines and encoded polylines; falls back to Valhalla walk, then car, when no transit route is available.

Client-side consumers: src/services/geo.service.ts (boundaries) and src/services/routeTransit.service.ts (point-to-point routing, exposing fetchRouteLeg and fetchAirportLeg).

Data model (short version)

User 1──N Trip (owner)         Trip N──N User (collaborators)
Trip N──N Attraction (attractionIds, shared/global entity)
Trip 1──N ScheduleEntry (Trip.schedules — keyed by attractionId, or a synthetic
                          "cs-*"/"fl-*" id for schedule-only custom-slots/flights)
Attraction N──N AttractionType ──1 AttractionCategory

Full field-level ERD: SPEC.md.

This is the beginning of the README. Read the rest at the original. Read the full README ↗