# Valhalla Routing Engine

This directory contains the configuration and setup for the Valhalla routing engine.

## 🚀 Quick Setup

### 1. Download OSM Data

Download OpenStreetMap data for your region from [Geofabrik](https://download.geofabrik.de/):

```bash
# For Vietnam/Southeast Asia
wget https://download.geofabrik.de/asia/vietnam-latest.osm.pbf -P custom_files/

# For smaller regions (Ho Chi Minh City area)
wget https://download.geofabrik.de/asia/vietnam-latest.osm.pbf -P custom_files/
```

### 2. Build and Run

```bash
# Build Valhalla container
docker-compose up -d valhalla

# Check status
curl http://localhost:8002/status
```

## 📊 API Endpoints

### Route Calculation
```bash
# POST /route
curl -X POST http://localhost:8002/route \
  -H "Content-Type: application/json" \
  -d '{
    "locations": [
      {"lat": 10.7769, "lon": 106.7009},
      {"lat": 10.7796, "lon": 106.7019}
    ],
    "costing": "auto",
    "directions_options": {
      "units": "kilometers"
    }
  }'
```

### Locate Nearby Roads
```bash
# POST /locate
curl -X POST http://localhost:8002/locate \
  -H "Content-Type: application/json" \
  -d '{
    "locations": [
      {"lat": 10.7769, "lon": 106.7009}
    ],
    "costing": "auto"
  }'
```

### Health Check
```bash
# GET /status
curl http://localhost:8002/status
```

## ⚙️ Configuration

The `valhalla.json` file contains the routing engine configuration:

- **Costing models**: auto, bicycle, pedestrian
- **Data sources**: OpenStreetMap
- **Service endpoints**: route, locate, status
- **Logging**: Configurable log levels

## 🗺️ Supported Regions

Current OSM data includes:
- Vietnam (complete)
- Southeast Asia (partial)
- Custom boundary areas

To add new regions:
1. Download `.osm.pbf` files to `custom_files/`
2. Restart the container
3. Wait for data processing to complete

## 🔧 Performance Tuning

### Memory Configuration
```json
{
  "mjolnir": {
    "tile_dir": "/data/valhalla",
    "max_cache_size": 1000000000
  }
}
```

### Costing Options
```json
{
  "costing_options": {
    "auto": {
      "maneuver_penalty": 5,
      "gate_cost": 30,
      "toll_booth_cost": 15
    }
  }
}
```

## 📈 Monitoring

### Health Checks
- Container status: `docker ps`
- Service health: `curl http://localhost:8002/status`
- Logs: `docker logs valhalla`

### Performance Metrics
- Route calculation time
- Memory usage
- Cache hit rate
- Request throughput

## 🐛 Troubleshooting

### Common Issues

1. **Container won't start**
   - Check OSM data files in `custom_files/`
   - Verify memory allocation (minimum 2GB)
   - Check port conflicts

2. **Slow route calculation**
   - Increase cache size in configuration
   - Optimize OSM data for your region
   - Add more memory to container

3. **Routes not found**
   - Verify coordinates are within OSM data bounds
   - Check road connectivity
   - Try different costing models

### Debug Mode
```bash
# Enable debug logging
docker-compose up valhalla --build
docker logs -f valhalla
```

## 🔄 Updates

### Update OSM Data
```bash
# Download new data
wget https://download.geofabrik.de/asia/vietnam-latest.osm.pbf -P custom_files/

# Rebuild container
docker-compose down valhalla
docker-compose up -d valhalla --build
```

### Update Valhalla Version
```bash
# Update base image in Dockerfile
# Rebuild container
docker-compose build valhalla --no-cache
```