# Line of Sight 🌍

Interactive web application that visualizes lines of sight around the Earth, showing major conurbations along any selected path.

## 🚀 Features

- **Interactive Map**: Click anywhere to select starting coordinates
- **360° Direction Selector**: Choose any direction with compass-style control
- **Fuzziness Tolerance**: Adjustable search radius around the line of sight
- **Tube-Line Visualization**: Shows up to 20 major cities along the path
- **Real-time Rendering**: Instant feedback on map with city markers
- **Map Style Toggle**: Switch between light and dark themes

## 🛠️ Tech Stack

### Frontend
- **Framework**: React 18
- **Map Library**: MapLibre GL JS
- **HTTP Client**: Axios
- **Styling**: Custom CSS

### Backend
- **Runtime**: Node.js 18
- **Framework**: Express.js
- **Database**: PostgreSQL 15 with PostGIS 3.3

### DevOps
- **Containerization**: Docker + Docker Compose
- **Database**: PostGIS spatial extension

## 📋 Prerequisites

- Docker 20.10+
- Docker Compose 2.0+
- Git (for repository access)

## 🚦 Getting Started

### 1. Clone Repository

```bash
git clone https://repos.retroweb.dev/ai-zone/line-of-sight.git
cd line-of-sight
```

### 2. Run with Docker

```bash
docker-compose up --build
```

### 3. Access Application

- **Frontend**: http://localhost:3050
- **Backend API**: http://localhost:3001
- **Database**: localhost:5432 (PostgreSQL with PostGIS)

## 🎮 How to Use

1. **Select Point**: Click anywhere on the map to set your starting coordinate
2. **Set Direction**: Use the slider to choose 0-360° direction
3. **Adjust Tolerance**: Set fuzziness (how close cities must be to the line)
4. **Show Line of Sight**: Click the button to visualize the path
5. **View Results**: See up to 20 major conurbations along the path

## 🧪 Running Tests

### Backend Tests
```bash
docker-compose exec backend npm test
```

### Frontend Tests
```bash
docker-compose exec frontend npm test
```

## 📡 API Endpoints

### GET /api/line-of-sight
Returns conurbations along a line of sight.

**Parameters:**
- `lat` (float): Starting latitude
- `lon` (float): Starting longitude
- `direction` (int): Direction in degrees (0-360)
- `tolerance` (int): Fuzziness tolerance in km (default: 50)

**Response:**
```json
{
  "success": true,
  "data": {
    "start_point": { "lat": 51.5074, "lon": -0.1278 },
    "direction": 45,
    "tolerance_km": 50,
    "conurbations": [...],
    "line_coordinates": [...]
  }
}
```

### GET /api/health
Health check endpoint.

## 🐳 Docker Commands

### Start Services
```bash
docker-compose up
```

### Start in Background
```bash
docker-compose up -d
```

### Stop Services
```bash
docker-compose down
```

### Rebuild and Start
```bash
docker-compose up --build
```

### View Logs
```bash
docker-compose logs -f
```

### Access Database
```bash
docker-compose exec postgres psql -U line_of_sight -d line_of_sight
```

## 📁 Project Structure

```
line_of_sight/
├── backend/
│   ├── app/
│   │   └── server.js          # Express API server
│   ├── tests/                 # Backend tests
│   ├── Dockerfile
│   └── package.json
├── frontend/
│   ├── src/
│   │   ├── App.js            # Main React component
│   │   ├── services/         # API client
│   │   └── styles/           # CSS files
│   ├── public/
│   ├── Dockerfile
│   └── package.json
├── docker/
│   └── init.sql              # Database initialization
├── docker-compose.yml        # Container orchestration
├── README.md                 # This file
└── .gitignore
```

## 🧩 Development

### Frontend Development
```bash
cd frontend
npm install
npm start
```

### Backend Development
```bash
cd backend
npm install
npm run dev
```

## 📝 Current Status

**MVP Version 1.0**

- ✅ Interactive map with coordinate selection
- ✅ Direction selector (0-360°)
- ✅ Fuzziness tolerance control
- ✅ Mock API returning 20 conurbations
- ✅ Line visualization on map
- ✅ City markers with popup info
- ⏳ Real geospatial calculations (Phase 2)
- ⏳ Natural Earth data import (Phase 2)
- ⏳ GeoNames integration (Phase 3)

## 🔮 Roadmap

### Phase 1: MVP ✅
- Basic map interface
- Dummy API endpoints
- Docker containerization

### Phase 2: Real Geospatial
- Great circle calculations
- PostGIS queries with ST_DWithin()
- Natural Earth data import

### Phase 3: Enhanced Features
- GeoNames dataset integration
- 3D globe visualization
- Distance calculations
- Performance optimization

### Phase 4: Production Ready
- User authentication
- Saved searches
- Export functionality
- Mobile optimization

## 🐛 Troubleshooting

### Port Already in Use
```bash
# Find process using port
lsof -i :3050
lsof -i :3001

# Kill process
kill -9 <PID>
```

### Database Connection Issues
```bash
# Check if database is running
docker-compose ps

# Restart database
docker-compose restart postgres
```

### Build Issues
```bash
# Clean and rebuild
docker-compose down
docker-compose build --no-cache
docker-compose up
```

## 🤝 Contributing

1. Create a feature branch
2. Make your changes
3. Add tests for new functionality
4. Ensure all tests pass
5. Submit a Pull Request

## 📄 License

MIT License

## 📞 Support

For issues or questions, please open an issue on the repository.

---

*Built with ❤️ by Agent Zero*