line-of-sight/README.md

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

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

2. Run with Docker

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

docker-compose exec backend npm test

Frontend Tests

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:

{
  "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

docker-compose up

Start in Background

docker-compose up -d

Stop Services

docker-compose down

Rebuild and Start

docker-compose up --build

View Logs

docker-compose logs -f

Access Database

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

cd frontend
npm install
npm start

Backend Development

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

# Find process using port
lsof -i :3050
lsof -i :3001

# Kill process
kill -9 <PID>

Database Connection Issues

# Check if database is running
docker-compose ps

# Restart database
docker-compose restart postgres

Build Issues

# 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