# Location Database Documentation

## Database File
- **Filename:** `locations.sqlite`
- **Type:** SQLite 3.x database
- **Encoding:** UTF-8
- **Current Records:** 367 location entries

## Database Schema

### Location Table

| Column | Type | Required | Default | Description |
|--------|------|----------|---------|-------------|
| `id` | INTEGER | - | AUTO_INCREMENT | Primary key |
| `latitude` | REAL | Yes | - | GPS latitude coordinate |
| `longitude` | REAL | Yes | - | GPS longitude coordinate |
| `timestamp` | TEXT | Yes | - | Time when location was recorded |
| `user_id` | INTEGER | No | 0 | Telegram user ID |
| `first_name` | TEXT | No | - | User's first name |
| `last_name` | TEXT | No | - | User's last name |
| `username` | TEXT | No | - | Telegram username |
| `marker_label` | TEXT | No | - | Custom label for map marker |
| `display_time` | TEXT | No | - | Formatted time for display |
| `chat_id` | INTEGER | No | 0 | Telegram chat ID |
| `battery` | INTEGER | No | - | Device battery level (0-100) |
| `speed` | REAL | No | - | Movement speed |
| `created_at` | TEXT | No | datetime('now') | Database insertion timestamp |

## Database Tables
- `Location` - Main table storing location data
- `sqlite_sequence` - SQLite internal table for auto-increment tracking

## Verification Commands

### Check database file
```bash
file locations.sqlite
```

### List all tables
```bash
sqlite3 locations.sqlite "SELECT name FROM sqlite_master WHERE type='table';"
```

### View table schema
```bash
sqlite3 locations.sqlite "PRAGMA table_info(Location);"
```

### Count records
```bash
sqlite3 locations.sqlite "SELECT COUNT(*) FROM Location;"
```

### Sample query
```bash
sqlite3 locations.sqlite "SELECT id, latitude, longitude, timestamp, user_id FROM Location LIMIT 5;"
```

## Future Development Ideas

### Potential Features
- [ ] Location history visualization
- [ ] Geofencing alerts
- [ ] Route tracking and analysis
- [ ] Speed monitoring and statistics
- [ ] Battery level tracking over time
- [ ] Multi-user location comparison
- [ ] Export to GPX/KML formats
- [ ] Privacy controls and data retention policies

### Optimization Opportunities
- [ ] Add indexes on frequently queried columns (user_id, timestamp)
- [ ] Implement data archival for old records
- [ ] Add spatial queries support (SQLite R*Tree extension)
- [ ] Implement location clustering for map display

### Integration Points
- [ ] REST API for location queries
- [ ] Real-time location updates via WebSocket/MQTT
- [ ] Map visualization frontend
- [ ] Mobile app data sync
- [ ] Export/backup functionality