# TravelTalk Full Documentation

> TravelTalk (https://www.traveltalknow.com/) is a progressive web app designed for travelers to acquire conversational fluency in real-world travel situations.

## Product Architecture

### Target Languages Supported
1. English (en)
2. Spanish (es)
3. French (fr)
4. German (de)
5. Italian (it)
6. Japanese (ja)
7. Hindi (hi)
8. Marathi (mr)
9. Chinese (zh)
10. Portuguese (pt)
11. Arabic (ar)
12. Korean (ko)
13. Russian (ru)

### Core Practice Modes
- **Situational Mission Maps**: Serpentine travel routes covering Airport, Taxi, Hotel Check-in, Cafe Ordering, Bar Socializing, Nightlife Dating, Emergency Assistance, and Shopping.
- **2-Minute Practice Sprints**: Rapid voice practice checklists with audio reference controls and instant feedback.
- **Cultural Etiquette Protocols**: Destination guides covering tipping rules, greeting customs, body language, dining etiquette, and taboo phrases.
- **AI Voice Dialogue Window**: Real-time voice practice with speech recognition, customizable voice speeds, and AI partner personas.

### Leaderboard & Ranking System
- **Calculated KPI Score**: `(XP * 0.4) + (Streak * 25) + (Missions * 15) + (Accuracy * 20)`
- **Traveler Ranks**: Ranks #1 through #50+ ranging from Novice Traveler to Polyglot Ambassador.

## API Specification Overview

- `GET /api/v1/travel/languages`: Returns supported target languages and native translations.
- `GET /api/v1/travel/journeys`: Retrieves destination chapters, mission routes, and situational dialogue trees.
- `GET /api/v1/users/me/activity`: Paginated user practice event history.
- `POST /api/v1/users/me/missions/complete`: Submit mission score, accuracy, and XP rewards.