Add initial documentation and test placeholders
- Comprehensive README.md with run instructions - Backend test structure (server.test.js) - Frontend test structure (App.test.js) - Setup instructions and troubleshooting guide - API documentation and project structure overview
This commit is contained in:
Agent Zero
@@ -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*
|
||||
@@ -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);
|
||||
});
|
||||
});
|
||||
});
|
||||
@@ -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);
|
||||
});
|
||||
});
|
||||
});
|
||||
Reference in New Issue
Block a user