Merge pull request 'Add initial documentation and test placeholders' (#1) from docs-initial into main

Reviewed-on: #1

README.md

@@ -0,0 +1,264 @@
+# 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:3000
+- **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 :3000
+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*

backend/tests/server.test.js

@@ -0,0 +1,42 @@
+/**
+ * Placeholder test file for Line of Sight Backend
+ * 
+ * TODO: Add real tests for:
+ * - API endpoint validation
+ * - Geospatial calculations
+ * - Database queries
+ * - Error handling
+ */
+
+describe('Line of Sight Backend', () => {
+  describe('GET /api/health', () => {
+    test('should return 200 OK', () => {
+      // TODO: Implement health check test
+      expect(true).toBe(true);
+    });
+  });
+
+  describe('GET /api/line-of-sight', () => {
+    test('should return valid response structure', () => {
+      // TODO: Implement line of sight API test
+      expect(true).toBe(true);
+    });
+
+    test('should handle missing parameters', () => {
+      // TODO: Implement error handling test
+      expect(true).toBe(true);
+    });
+  });
+
+  describe('Geospatial Calculations', () => {
+    test('should calculate great circle path', () => {
+      // TODO: Implement geospatial calculation tests
+      expect(true).toBe(true);
+    });
+
+    test('should filter cities within tolerance', () => {
+      // TODO: Implement tolerance filtering tests
+      expect(true).toBe(true);
+    });
+  });
+});

frontend/src/__tests__/App.test.js

@@ -0,0 +1,53 @@
+/**
+ * Placeholder test file for Line of Sight Frontend
+ * 
+ * TODO: Add real tests for:
+ * - Map component rendering
+ * - Direction selector functionality
+ * - API integration
+ * - User interactions
+ * - Line of sight visualization
+ */
+
+describe('Line of Sight Frontend', () => {
+  describe('App Component', () => {
+    test('should render map container', () => {
+      // TODO: Implement component rendering test
+      expect(true).toBe(true);
+    });
+
+    test('should display direction selector', () => {
+      // TODO: Implement direction selector test
+      expect(true).toBe(true);
+    });
+
+    test('should handle map click events', () => {
+      // TODO: Implement click event test
+      expect(true).toBe(true);
+    });
+  });
+
+  describe('API Integration', () => {
+    test('should fetch line of sight data', () => {
+      // TODO: Implement API fetch test
+      expect(true).toBe(true);
+    });
+
+    test('should handle API errors gracefully', () => {
+      // TODO: Implement error handling test
+      expect(true).toBe(true);
+    });
+  });
+
+  describe('UI Components', () => {
+    test('should toggle map style between light/dark', () => {
+      // TODO: Implement style toggle test
+      expect(true).toBe(true);
+    });
+
+    test('should display conurbation results table', () => {
+      // TODO: Implement results table test
+      expect(true).toBe(true);
+    });
+  });
+});