# Street Lingo Platform 🌍

Learn languages through real-world scenarios with AI-powered conversations.

## Available Languages

### 🇮🇩 Indonesian (Learn Indonesian)
- **URL**: `http://localhost:3000`
- **Scenarios**: Warung, Ojek, Alfamart, Coffee Shop
- **Focus**: Everyday Indonesian conversations and cultural contexts

### 🇩🇪 German (Deutsch lernen in Berlin)
- **URL**: `http://localhost:3001`  
- **Scenarios**: Späti, WG Viewing, Bürgeramt, Biergarten, U-Bahn
- **Focus**: Berlin-specific German for expats

## Quick Start

### Prerequisites
- Python 3.8+
- Node.js 16+
- Google Cloud credentials (for Speech-to-Text and Text-to-Speech)
- OpenAI API key

### 1. Environment Setup
```bash
# Backend environment
cp backend/.env.example backend/.env
# Edit backend/.env with your API keys

# Set up Google Cloud credentials
export GOOGLE_APPLICATION_CREDENTIALS="path/to/your/service-account-key.json"
```

### 2. Install Dependencies
```bash
# Backend dependencies
cd backend
pip install -r requirements.txt

# Indonesian app dependencies (if not already installed)
cd ..
npm install

# German app dependencies
cd apps/german-app
npm install
```

### 3. Start All Services
```bash
# From the project root
./start-street-lingo.sh
```

This will start:
- Backend API server on port 8000
- Indonesian app on port 3000
- German app on port 3001

## Manual Setup (Alternative)

### Backend
```bash
cd backend
python main.py
```

### Indonesian App
```bash
npm run dev
```

### German App
```bash
cd apps/german-app
npm run dev
```

## API Endpoints

### Language-Specific Scenarios
- `GET /api/scenarios/indonesian` - Indonesian scenarios
- `GET /api/scenarios/german` - German scenarios
- `GET /api/scenarios` - All scenarios for all languages

### WebSocket Connections
- `ws://localhost:8000/ws/speech/indonesian` - Indonesian speech interface
- `ws://localhost:8000/ws/speech/german` - German speech interface

### Translation
- `POST /api/translate` - Translate text between languages

## Architecture

```
street-lingo/
├── backend/                    # Shared backend
│   ├── core/                  # Core language-agnostic services
│   ├── languages/             # Language-specific implementations
│   │   ├── indonesian/        # Indonesian models & services
│   │   └── german/            # German models & services
│   └── main.py               # Main FastAPI application
├── src/                       # Indonesian frontend
├── apps/german-app/           # German frontend
└── start-street-lingo.sh     # Startup script
```

## Features

### 🎙️ Speech Recognition
- Real-time speech-to-text in Indonesian and German
- Optimized for conversational speech patterns

### 🗣️ Text-to-Speech
- Character-specific voices for immersive conversations
- Indonesian: Chirp3-HD voices
- German: Neural2 voices with regional characteristics

### 🤖 AI Conversations
- Context-aware conversations using OpenAI GPT
- Goal-based learning with progress tracking
- Cultural and linguistic authenticity

### 🎯 Scenario-Based Learning
- Real-world situations you'll encounter
- Progressive difficulty and goal completion
- Immediate feedback and corrections

## Development

### Adding New Languages
1. Create new language directory in `backend/languages/`
2. Implement language-specific models and services
3. Create frontend app in `apps/[language]-app/`
4. Update routing in `main.py`

### Adding New Scenarios
1. Define scenarios in `backend/languages/[language]/models.py`
2. Create personality with goals and helpful phrases
3. Add to `SCENARIO_PERSONALITIES` dictionary

## Environment Variables

### Backend (.env)
```
OPENAI_API_KEY=your_openai_api_key
GOOGLE_APPLICATION_CREDENTIALS=path/to/service-account.json
SPEECH_ENCODING=WEBM_OPUS
SPEECH_SAMPLE_RATE=48000
TTS_LANGUAGE_CODE=id-ID  # or de-DE
HOST=localhost
PORT=8000
DEBUG=true
```

### Frontend
```
VITE_WS_BASE_URL=ws://localhost:8000
VITE_API_BASE_URL=http://localhost:8000
```

## Troubleshooting

### Common Issues

1. **WebSocket Connection Failed**
   - Check if backend is running on port 8000
   - Verify CORS settings in backend

2. **Speech Recognition Not Working**
   - Ensure microphone permissions are granted
   - Check Google Cloud credentials

3. **Audio Playback Issues**
   - Verify browser audio permissions
   - Check TTS service configuration

4. **API Errors**
   - Verify OpenAI API key is valid
   - Check Google Cloud Speech/TTS quotas

### Logs
- Backend logs: Console output from `python main.py`
- Frontend logs: Browser developer console
- WebSocket logs: Network tab in browser dev tools

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new features
5. Submit a pull request

## License

This project is licensed under the MIT License. See LICENSE file for details.

## Support

For issues and questions:
- Open an issue on GitHub
- Check the troubleshooting section
- Review API documentation at `http://localhost:8000/docs`