# jxtoast/smart_itinerary architecture > Architecture diagram of the GitHub repository jxtoast/smart_itinerary, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-10). It is an AI-made overview: check details against the source. - Interactive diagram: https://gitdiagram.com/jxtoast/smart_itinerary - Repository: https://github.com/jxtoast/smart_itinerary ## Overview 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: [`apps/web/app`](https://github.com/jxtoast/smart_itinerary/tree/main/apps/web/app) (Next.js app), [`services/gemini-service/src/routes/geminiRoutes.ts`](https://github.com/jxtoast/smart_itinerary/blob/main/services/gemini-service/src/routes/geminiRoutes.ts) (AI planning service), [`services/gateway/src/proxy.ts`](https://github.com/jxtoast/smart_itinerary/blob/main/services/gateway/src/proxy.ts) (API gateway), [`services/tools-service/src/routes/groups.routes.ts`](https://github.com/jxtoast/smart_itinerary/blob/main/services/tools-service/src/routes/groups.routes.ts) (Groups and shares) ## Diagram (Mermaid) ```mermaid flowchart TD subgraph group_web["Web experience"] node_webapp["Next.js app"] node_api["Browser API client
[client.ts]"] node_hotelui["Hotel search UI"] end subgraph group_platform["Gateway and contracts"] node_gateway["API gateway
[proxy.ts]"] node_contracts["Shared contracts"] node_adapters["Infrastructure adapters"] node_broker["Event broker
[broker.ts]"] node_storage[("PDF object storage
[storage.ts]")] end subgraph group_planning["Trip planning"] node_gemini["AI planning service
[geminiRoutes.ts]"] node_planner["Itinerary planner"] node_prompts["Generation prompts
[prompts.ts]"] node_flights["Flight search
[FlightsService.ts]"] node_reference["Reference data
[fetchStrategies.ts]"] end subgraph group_identity["Identity and trips"] node_auth["Authentication service
[app.ts]"] node_demographics["Travel preferences"] node_itinerary["Itinerary service
[itineraryRoutes.ts]"] node_itinerarydb[("Itinerary database")] end subgraph group_collaboration["Sharing and delivery"] node_tools["Tools service
[app.ts]"] node_groups["Groups and shares
[groups.routes.ts]"] node_exports["PDF export
[export.routes.ts]"] node_toolsdb[("Tools database
[toolsRepository.ts]")] node_email["Email service
[handlers.ts]"] end node_traveler(("Traveler")) node_mail["Email inbox"] node_ai_provider["Gemini provider"] node_flight_provider["Flight data provider"] node_traveler -->|"uses"| node_webapp node_webapp -->|"requests"| node_api node_api -->|"proxies API"| node_gateway node_gateway -->|"routes auth"| node_auth node_gateway -->|"routes trips"| node_itinerary node_gateway -->|"routes planning"| node_gemini node_gateway -->|"routes tools"| node_tools node_api -->|"uses DTOs"| node_contracts node_auth -->|"mounts routes"| node_demographics node_demographics -->|"validates DTOs"| node_contracts node_webapp -->|"requests trip plan"| node_gemini node_gemini -->|"plans itinerary"| node_planner node_planner -.->|"generates content"| node_prompts node_gemini -->|"searches flights"| node_flights node_gemini -->|"fetches options"| node_reference node_gemini -.->|"generates with AI"| node_ai_provider node_flights -.->|"queries flight data"| node_flight_provider node_webapp -->|"saves trips"| node_itinerary node_itinerary -->|"reads and writes"| node_itinerarydb node_webapp -->|"offers hotel search"| node_hotelui node_hotelui -->|"requests suggestions"| node_gemini node_webapp -->|"manages groups"| node_groups node_groups -->|"reads and writes"| node_toolsdb node_webapp -->|"creates share links"| node_groups node_groups -->|"fetches shared trip"| node_itinerary node_groups -.->|"publishes share events"| node_broker node_webapp -->|"requests PDF"| node_exports node_exports -->|"records exports"| node_toolsdb node_exports -->|"stores PDF"| node_storage node_itinerary -.->|"publishes trip events"| node_broker node_broker -->|"delivers events"| node_email node_email -->|"sends reminders"| node_mail node_adapters -->|"provides event adapter"| node_broker node_adapters -->|"provides storage adapter"| node_storage click node_webapp "https://github.com/jxtoast/smart_itinerary/tree/main/apps/web/app" click node_api "https://github.com/jxtoast/smart_itinerary/blob/main/packages/api-client/src/client.ts" click node_gateway "https://github.com/jxtoast/smart_itinerary/blob/main/services/gateway/src/proxy.ts" click node_contracts "https://github.com/jxtoast/smart_itinerary/tree/main/packages/shared/src/dto" click node_adapters "https://github.com/jxtoast/smart_itinerary/tree/main/packages/shared/src/adapters" click node_auth "https://github.com/jxtoast/smart_itinerary/blob/main/services/auth-service/src/app.ts" click node_demographics "https://github.com/jxtoast/smart_itinerary/blob/main/services/auth-service/src/routes/demographics.routes.ts" click node_itinerary "https://github.com/jxtoast/smart_itinerary/blob/main/services/itinerary-service/src/routes/itineraryRoutes.ts" click node_itinerarydb "https://github.com/jxtoast/smart_itinerary/blob/main/services/itinerary-service/src/repositories/itineraryRepository.ts" click node_gemini "https://github.com/jxtoast/smart_itinerary/blob/main/services/gemini-service/src/routes/geminiRoutes.ts" click node_planner "https://github.com/jxtoast/smart_itinerary/blob/main/services/gemini-service/src/plan/ItineraryPlannerFacade.ts" click node_prompts "https://github.com/jxtoast/smart_itinerary/blob/main/services/gemini-service/src/gemini/prompts.ts" click node_flights "https://github.com/jxtoast/smart_itinerary/blob/main/services/gemini-service/src/flights/FlightsService.ts" click node_reference "https://github.com/jxtoast/smart_itinerary/blob/main/services/gemini-service/src/reference/fetchStrategies.ts" click node_hotelui "https://github.com/jxtoast/smart_itinerary/blob/main/apps/web/components/hotel/HotelSearchComponent.tsx" click node_tools "https://github.com/jxtoast/smart_itinerary/blob/main/services/tools-service/src/app.ts" click node_groups "https://github.com/jxtoast/smart_itinerary/blob/main/services/tools-service/src/routes/groups.routes.ts" click node_exports "https://github.com/jxtoast/smart_itinerary/blob/main/services/tools-service/src/routes/export.routes.ts" click node_toolsdb "https://github.com/jxtoast/smart_itinerary/blob/main/services/tools-service/src/repositories/toolsRepository.ts" click node_email "https://github.com/jxtoast/smart_itinerary/blob/main/services/email-service/src/handlers.ts" click node_broker "https://github.com/jxtoast/smart_itinerary/blob/main/packages/shared/src/adapters/broker.ts" click node_storage "https://github.com/jxtoast/smart_itinerary/blob/main/packages/shared/src/adapters/storage.ts" classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554 classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337 classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81 classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a class node_webapp,node_api,node_hotelui toneBlue class node_gateway,node_contracts,node_adapters,node_broker,node_storage toneAmber class node_gemini,node_planner,node_prompts,node_flights,node_reference toneMint class node_auth,node_demographics,node_itinerary,node_itinerarydb toneRose class node_tools,node_groups,node_exports,node_toolsdb,node_email,node_traveler,node_mail,node_ai_provider,node_flight_provider toneIndigo ``` ## Components ### Web experience - [Next.js app](https://github.com/jxtoast/smart_itinerary/tree/main/apps/web/app): `apps/web/app` - [Browser API client](https://github.com/jxtoast/smart_itinerary/blob/main/packages/api-client/src/client.ts): `packages/api-client/src/client.ts` - [Hotel search UI](https://github.com/jxtoast/smart_itinerary/blob/main/apps/web/components/hotel/HotelSearchComponent.tsx): `apps/web/components/hotel/HotelSearchComponent.tsx` ### Gateway and contracts - [API gateway](https://github.com/jxtoast/smart_itinerary/blob/main/services/gateway/src/proxy.ts): `services/gateway/src/proxy.ts` - [Shared contracts](https://github.com/jxtoast/smart_itinerary/tree/main/packages/shared/src/dto): `packages/shared/src/dto` - [Infrastructure adapters](https://github.com/jxtoast/smart_itinerary/tree/main/packages/shared/src/adapters): `packages/shared/src/adapters` - [Event broker](https://github.com/jxtoast/smart_itinerary/blob/main/packages/shared/src/adapters/broker.ts): `packages/shared/src/adapters/broker.ts` - [PDF object storage](https://github.com/jxtoast/smart_itinerary/blob/main/packages/shared/src/adapters/storage.ts): `packages/shared/src/adapters/storage.ts` ### Trip planning - [AI planning service](https://github.com/jxtoast/smart_itinerary/blob/main/services/gemini-service/src/routes/geminiRoutes.ts): `services/gemini-service/src/routes/geminiRoutes.ts` - [Itinerary planner](https://github.com/jxtoast/smart_itinerary/blob/main/services/gemini-service/src/plan/ItineraryPlannerFacade.ts): `services/gemini-service/src/plan/ItineraryPlannerFacade.ts` - [Generation prompts](https://github.com/jxtoast/smart_itinerary/blob/main/services/gemini-service/src/gemini/prompts.ts): `services/gemini-service/src/gemini/prompts.ts` - [Flight search](https://github.com/jxtoast/smart_itinerary/blob/main/services/gemini-service/src/flights/FlightsService.ts): `services/gemini-service/src/flights/FlightsService.ts` - [Reference data](https://github.com/jxtoast/smart_itinerary/blob/main/services/gemini-service/src/reference/fetchStrategies.ts): `services/gemini-service/src/reference/fetchStrategies.ts` ### Identity and trips - [Authentication service](https://github.com/jxtoast/smart_itinerary/blob/main/services/auth-service/src/app.ts): `services/auth-service/src/app.ts` - [Travel preferences](https://github.com/jxtoast/smart_itinerary/blob/main/services/auth-service/src/routes/demographics.routes.ts): `services/auth-service/src/routes/demographics.routes.ts` - [Itinerary service](https://github.com/jxtoast/smart_itinerary/blob/main/services/itinerary-service/src/routes/itineraryRoutes.ts): `services/itinerary-service/src/routes/itineraryRoutes.ts` - [Itinerary database](https://github.com/jxtoast/smart_itinerary/blob/main/services/itinerary-service/src/repositories/itineraryRepository.ts): `services/itinerary-service/src/repositories/itineraryRepository.ts` ### Sharing and delivery - [Tools service](https://github.com/jxtoast/smart_itinerary/blob/main/services/tools-service/src/app.ts): `services/tools-service/src/app.ts` - [Groups and shares](https://github.com/jxtoast/smart_itinerary/blob/main/services/tools-service/src/routes/groups.routes.ts): `services/tools-service/src/routes/groups.routes.ts` - [PDF export](https://github.com/jxtoast/smart_itinerary/blob/main/services/tools-service/src/routes/export.routes.ts): `services/tools-service/src/routes/export.routes.ts` - [Tools database](https://github.com/jxtoast/smart_itinerary/blob/main/services/tools-service/src/repositories/toolsRepository.ts): `services/tools-service/src/repositories/toolsRepository.ts` - [Email service](https://github.com/jxtoast/smart_itinerary/blob/main/services/email-service/src/handlers.ts): `services/email-service/src/handlers.ts` ### Other components - **Traveler** - **Email inbox** - **Gemini provider** - **Flight data provider** ## Connections - 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 (evidence: `packages/api-client/src/client.ts`) - Authentication service → Travel preferences: mounts routes (evidence: `services/auth-service/src/app.ts`) - Travel preferences → Shared contracts: validates DTOs (evidence: `services/auth-service/src/routes/demographics.routes.ts`) - Next.js app → AI planning service: requests trip plan - AI planning service → Itinerary planner: plans itinerary (evidence: `services/gemini-service/src/routes/geminiRoutes.ts`) - Itinerary planner → Generation prompts: generates content - AI planning service → Flight search: searches flights (evidence: `services/gemini-service/src/routes/geminiRoutes.ts`) - AI planning service → Reference data: fetches options (evidence: `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 (evidence: `services/itinerary-service/src/routes/itineraryRoutes.ts`) - Next.js app → Hotel search UI: offers hotel search - Hotel search UI → AI planning service: requests suggestions (evidence: `services/gemini-service/src/routes/geminiRoutes.ts`) - Next.js app → Groups and shares: manages groups - Groups and shares → Tools database: reads and writes (evidence: `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 (evidence: `services/tools-service/src/routes/export.routes.ts`) - PDF export → PDF object storage: stores PDF (evidence: `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 (evidence: `packages/shared/src/server.ts`) - Infrastructure adapters → PDF object storage: provides storage adapter (evidence: `packages/shared/src/server.ts`)