Kontour AI

AI-powered travel planning workspace that combines chat, map, and itinerary management in a single interface. The project is built with Lit + Vite and includes session persistence, context extraction, activity orchestration, sharing, and booking-oriented workflows.

Core Systems

1) Chatbot Intelligence

• Psychologist-guided, subtle question sequencing to progressively uncover trip intent without overwhelming users
• Context-aware recommendation flow designed to improve relevance, planning confidence, and decision quality turn-by-turn

2) Map Intelligence

• Smart route calculation and map orchestration integrated into planning flows
• AI-generated navigation summaries for clearer travel decisions
• Route optimization inspired by operations research solver strategies

3) Reservation (GDS-Connected)

• One-stop booking workflow that can place real orders across travel components
• Bot-friendly booking interfaces and skill-compatible workflows for seamless automation

4) Itinerary and Sharing

• Structured itinerary planning and day-level activity coordination
• Creator-to-follower sharing through text, poster, video frame, and embeddable web widget formats

What This Project Provides

• Conversational trip planning with context-aware AI responses
• Map-driven planning with activity markers, routing, and location workflows
• Day-by-day itinerary editing with activity CRUD and transport controls
• Persistent multi-session state with storage recovery and migration support
• Flight/hotel recommendation and checkout orchestration components
• Share/export flows (including Google Maps export and token-based sharing)
• Internal conversation guidance and channel sanitization to keep user chat clean

Tech Stack

• Frontend: Lit, TypeScript, Vite
• AI: Google Gemini integrations (@google/genai, @google/generative-ai)
• Maps: Google Maps JavaScript API
• Validation/Schemas: Zod
• Testing: Vitest, Open WC testing utilities, Playwright (dependency present)

Architecture At a Glance

Primary runtime flow:

1. src/main.tsx bootstraps Application
2. Application initializes UI, services, MCP integration, and event wiring
3. AppLayout coordinates chat/map/itinerary state and session synchronization
4. MessageHandler processes user input, streams AI output, sanitizes public content
5. Session and trip-context services persist and reconcile state across modules

Key modules:

• src/components/ UI components (chat, map, itinerary, checkout, sharing)
• src/app/ application bootstrap and message pipeline
• src/services/ domain services (session, AI, context, export, sync, guidance)
• src/modules/ layout/map feature modules
• src/data/demo/ demo trip datasets

Foundation reference:

• Built on concepts from the Gemini MCP Maps project: MCP Maps Basic

Prerequisites

• Node.js 18+
• npm
• Google Maps API key
• Gemini API key

Environment Variables

Configured in src/config/environment.ts.

Required:

• VITE_GEMINI_API_KEY (or GEMINI_API_KEY)
• VITE_GOOGLE_MAPS_API_KEY (or GOOGLE_MAPS_API_KEY)

Optional (OL layer endpoints):

• VITE_OL_GRAPHQL_ENDPOINT (default: http://localhost:4000/graphql)
• VITE_OL_SSE_ENDPOINT (default: http://localhost:4000/api/events)

Getting Started

npm install
npm run dev

Build and preview:

npm run build
npm run preview

Available Scripts

Command	Purpose
npm run dev	Start Vite dev server
npm run dev:mem	Dev server with constrained Node memory
npm run build	TypeScript compile + production bundle
npm run preview	Preview production build
npm run type-check	TypeScript checks only
npm run lint	Alias to type-check in current setup
npm run test	Run Vitest
npm run test:unit	Unit test suite
npm run test:integration	Integration test suite
npm run test:coverage	Coverage run
npm run test:ui	Vitest UI
npm run audit:styles	Run style compliance audit

UI Layout Behavior

• Desktop/tablet: multi-panel chat + map + itinerary workspace
• Mobile: dedicated split-shell (map top, workspace bottom with pane switcher)
  • Implementation notes: docs/01-frontend/mobile-split-layout-implementation.md

Documentation Map

Core docs to start with:

• Frontend charter: docs/01-frontend/frontend-masterdocs/01-charter.md
• Frontend architecture: docs/01-frontend/frontend-masterdocs/02-architecture.md
• Conversation channel visibility update: docs/technical/conversation-channel-internal-visibility-migration-2026-02-09.md
• UI compliance/adaptivity remediation: docs/technical/ui-compliance-adaptivity-remediation-2026-02-09.md
• Activity card system update: docs/technical/activity-card-system-elasticity-update-2026-02-09.md

Testing Notes

• Unit and integration tests are organized under src/__tests__/
• Security-focused tests are under src/__tests__/security/
• Some workflows rely on browser APIs and map mocks; use repository test setup and avoid ad hoc environment assumptions

Troubleshooting

• Missing API keys: check src/config/environment.ts logs and variable names
• Empty/partial map behavior: verify Google Maps key and browser console for API load errors
• Session oddities after large refactors: inspect SessionManager and migration logic under src/services/session/
• Style regressions: run npm run audit:styles

CC BY-NC Agreement (Non-Commercial)

By accessing, using, copying, modifying, or sharing this repository, you agree to the following:

• Attribution is required for any reuse or redistribution.
• Commercial use is not allowed without prior written permission from the copyright holder.
• If you modify the project, you should clearly indicate that changes were made.

Hackathon Submission

• Devpost: https://devpost.com/software/let-s-trip-zu58wy
• YouTube description draft: docs/submission/youtube-description.md
• Demo assets:
  • Images: galleries/images/
  • Videos: galleries/videos/

License

This project is released under the Creative Commons Attribution-NonCommercial 4.0 International license (CC BY-NC 4.0).

• Human-readable summary: https://creativecommons.org/licenses/by-nc/4.0/
• Full legal code: https://creativecommons.org/licenses/by-nc/4.0/legalcode