How jxtoast/smart_itinerary works
Smart Itinerary is a browser-based, AI-assisted trip-planning application re-platformed as a Next.js frontend and backend microservices. The main workflow is to authenticate, plan a trip with AI-generated itinerary details and flight/weather information, save it, then optionally search hotels, share it with a group, export a PDF, and receive email reminders. The graph follows the README’s service map and sampled route wiring; several UI and service internals were not excerpted, so those connections are documented at the service level rather than inferred as code calls.
Main entry points: app Next.js app · geminiRoutes.ts AI planning service · proxy.ts API gateway · groups.routes.ts Groups and shares
Components 26
Web experience
- Next.js app
apps/web/app - Browser API client
packages/api-client/src/client.ts - Hotel search UI
apps/web/components/hotel/HotelSearchComponent.tsx
Gateway and contracts
- API gateway
services/gateway/src/proxy.ts - Shared contracts
packages/shared/src/dto - Infrastructure adapters
packages/shared/src/adapters - Event broker
packages/shared/src/adapters/broker.ts - PDF object storage
packages/shared/src/adapters/storage.ts
Trip planning
- AI planning service
services/gemini-service/src/routes/geminiRoutes.ts - Itinerary planner
services/gemini-service/src/plan/ItineraryPlannerFacade.ts - Generation prompts
services/gemini-service/src/gemini/prompts.ts - Flight search
services/gemini-service/src/flights/FlightsService.ts - Reference data
services/gemini-service/src/reference/fetchStrategies.ts
Identity and trips
- Authentication service
services/auth-service/src/app.ts - Travel preferences
services/auth-service/src/routes/demographics.routes.ts - Itinerary service
services/itinerary-service/src/routes/itineraryRoutes.ts - Itinerary database
services/itinerary-service/src/repositories/itineraryRepository.ts
Sharing and delivery
- Tools service
services/tools-service/src/app.ts - Groups and shares
services/tools-service/src/routes/groups.routes.ts - PDF export
services/tools-service/src/routes/export.routes.ts - Tools database
services/tools-service/src/repositories/toolsRepository.ts - Email service
services/email-service/src/handlers.ts
Other components
- Traveler
- Email inbox
- Gemini provider
- Flight data provider
Connections 34
- Traveler → Next.js app: uses
- Next.js app → Browser API client: requests
- Browser API client → API gateway: proxies API
- API gateway → Authentication service: routes auth
- API gateway → Itinerary service: routes trips
- API gateway → AI planning service: routes planning
- API gateway → Tools service: routes tools
- Browser API client → Shared contracts: uses DTOs
packages/api-client/src/client.ts - Authentication service → Travel preferences: mounts routes
services/auth-service/src/app.ts - Travel preferences → Shared contracts: validates DTOs
services/auth-service/src/routes/demographics.routes.ts - Next.js app → AI planning service: requests trip plan
- AI planning service → Itinerary planner: plans itinerary
services/gemini-service/src/routes/geminiRoutes.ts - Itinerary planner → Generation prompts: generates content
- AI planning service → Flight search: searches flights
services/gemini-service/src/routes/geminiRoutes.ts - AI planning service → Reference data: fetches options
services/gemini-service/src/routes/geminiRoutes.ts - AI planning service → Gemini provider: generates with AI
- Flight search → Flight data provider: queries flight data
- Next.js app → Itinerary service: saves trips
- Itinerary service → Itinerary database: reads and writes
services/itinerary-service/src/routes/itineraryRoutes.ts - Next.js app → Hotel search UI: offers hotel search
- Hotel search UI → AI planning service: requests suggestions
services/gemini-service/src/routes/geminiRoutes.ts - Next.js app → Groups and shares: manages groups
- Groups and shares → Tools database: reads and writes
services/tools-service/src/routes/groups.routes.ts - Next.js app → Groups and shares: creates share links
- Groups and shares → Itinerary service: fetches shared trip
- Groups and shares → Event broker: publishes share events
- Next.js app → PDF export: requests PDF
- PDF export → Tools database: records exports
services/tools-service/src/routes/export.routes.ts - PDF export → PDF object storage: stores PDF
packages/shared/src/adapters/storage.ts - Itinerary service → Event broker: publishes trip events
- Event broker → Email service: delivers events
- Email service → Email inbox: sends reminders
- Infrastructure adapters → Event broker: provides event adapter
packages/shared/src/server.ts - Infrastructure adapters → PDF object storage: provides storage adapter
packages/shared/src/server.ts