Move documentation to docs/ directory and improve terminology

- Move ARCHITECTURE.md and CLAUDE.md to docs/ directory - Replace "real-time" terminology with accurate "low-latency" and "high-performance" - Update README to reflect correct performance characteristics - Add comprehensive ICAO country database with SQLite backend - Fix display options positioning and functionality - Add map scale controls and improved range ring visibility - Enhance aircraft marker orientation and trail management 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
2025-08-24 16:24:46 +02:00 · 2025-08-24 16:24:46 +02:00 · 20bdcf54ec
commit 20bdcf54ec
parent 43e55b2ba0
15 changed files with 746 additions and 67 deletions
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@ -0,0 +1,290 @@
+# SkyView Architecture Documentation
+
+## Overview
+
+SkyView is a high-performance, multi-source ADS-B aircraft tracking system built in Go with a modern JavaScript frontend. It connects to multiple dump1090 Beast format receivers, performs intelligent data fusion, and provides low-latency aircraft tracking through a responsive web interface.
+
+## System Architecture
+
+```
+┌─────────────────┐    ┌──────────────┐    ┌─────────────────┐
+│   dump1090       │    │   dump1090   │    │   dump1090      │
+│   Receiver 1     │    │   Receiver 2 │    │   Receiver N    │
+│   Port 30005     │    │   Port 30005 │    │   Port 30005    │
+└─────────┬───────┘    └──────┬───────┘    └─────────┬───────┘
+          │                   │                      │
+          │ Beast Binary      │ Beast Binary         │ Beast Binary
+          │ TCP Stream        │ TCP Stream           │ TCP Stream
+          │                   │                      │
+          └───────────────────┼──────────────────────┘
+                              │
+                    ┌─────────▼──────────┐
+                    │   SkyView Server   │
+                    │                    │
+                    │ ┌────────────────┐ │
+                    │ │  Beast Client  │ │ ── Multi-source TCP clients
+                    │ │   Manager      │ │
+                    │ └────────────────┘ │
+                    │ ┌────────────────┐ │
+                    │ │  Mode S/ADS-B  │ │ ── Message parsing & decoding
+                    │ │    Decoder     │ │
+                    │ └────────────────┘ │
+                    │ ┌────────────────┐ │
+                    │ │  Data Merger   │ │ ── Intelligent data fusion
+                    │ │   & ICAO DB    │ │
+                    │ └────────────────┘ │
+                    │ ┌────────────────┐ │
+                    │ │ HTTP/WebSocket │ │ ── Low-latency web interface
+                    │ │    Server      │ │
+                    │ └────────────────┘ │
+                    └─────────┬──────────┘
+                              │
+                    ┌─────────▼──────────┐
+                    │   Web Interface    │
+                    │                    │
+                    │ • Interactive Maps │
+                    │ • Low-latency Updates│
+                    │ • Aircraft Details │
+                    │ • Coverage Analysis│
+                    │ • 3D Visualization │
+                    └────────────────────┘
+```
+
+## Core Components
+
+### 1. Beast Format Clients (`internal/client/`)
+
+**Purpose**: Manages TCP connections to dump1090 receivers
+
+**Key Features**:
+- Concurrent connection handling for multiple sources
+- Automatic reconnection with exponential backoff
+- Beast binary format parsing
+- Per-source connection monitoring and statistics
+
+**Files**:
+- `beast.go`: Main client implementation
+
+### 2. Mode S/ADS-B Decoder (`internal/modes/`)
+
+**Purpose**: Decodes raw Mode S and ADS-B messages into structured aircraft data
+
+**Key Features**:
+- CPR (Compact Position Reporting) decoding with zone ambiguity resolution
+- ADS-B message type parsing (position, velocity, identification)
+- Aircraft category and type classification
+- Signal quality assessment
+
+**Files**:
+- `decoder.go`: Core decoding logic
+
+### 3. Data Merger (`internal/merger/`)
+
+**Purpose**: Fuses aircraft data from multiple sources using intelligent conflict resolution
+
+**Key Features**:
+- Signal strength-based source selection
+- High-performance data fusion and conflict resolution
+- Aircraft state management and lifecycle tracking
+- Historical data collection (position, altitude, speed, signal trails)
+- Automatic stale aircraft cleanup
+
+**Files**:
+- `merger.go`: Multi-source data fusion engine
+
+### 4. ICAO Country Database (`internal/icao/`)
+
+**Purpose**: Provides comprehensive ICAO address to country mapping
+
+**Key Features**:
+- Embedded SQLite database with 70+ allocations covering 40+ countries
+- Based on official ICAO Document 8585
+- Fast range-based lookups using database indexing
+- Country names, ISO codes, and flag emojis
+
+**Files**:
+- `database.go`: SQLite database interface
+- `icao.db`: Embedded SQLite database with ICAO allocations
+
+### 5. HTTP/WebSocket Server (`internal/server/`)
+
+**Purpose**: Serves web interface and provides low-latency data streaming
+
+**Key Features**:
+- RESTful API for aircraft and system data
+- WebSocket connections for low-latency updates
+- Static asset serving with embedded resources
+- Coverage analysis and signal heatmaps
+
+**Files**:
+- `server.go`: HTTP server and WebSocket handler
+
+### 6. Web Frontend (`assets/static/`)
+
+**Purpose**: Interactive web interface for aircraft tracking and visualization
+
+**Key Technologies**:
+- **Leaflet.js**: Interactive maps and aircraft markers
+- **Three.js**: 3D radar visualization
+- **Chart.js**: Live statistics and charts
+- **WebSockets**: Live data streaming
+- **Responsive CSS**: Mobile-optimized interface
+
+**Files**:
+- `index.html`: Main web interface
+- `js/app.js`: Main application orchestrator
+- `js/modules/`: Modular JavaScript components
+  - `aircraft-manager.js`: Aircraft marker and trail management
+  - `map-manager.js`: Map controls and overlays
+  - `ui-manager.js`: User interface state management
+  - `websocket.js`: Low-latency data connections
+- `css/style.css`: Responsive styling and themes
+- `icons/`: SVG aircraft type icons
+
+## Data Flow
+
+### 1. Data Ingestion
+1. **Beast Clients** connect to dump1090 receivers via TCP
+2. **Beast Parser** processes binary message stream
+3. **Mode S Decoder** converts raw messages to structured aircraft data
+4. **Data Merger** receives aircraft updates with source attribution
+
+### 2. Data Fusion
+1. **Signal Analysis**: Compare signal strength across sources
+2. **Conflict Resolution**: Select best data based on signal quality and recency
+3. **State Management**: Update aircraft position, velocity, and metadata
+4. **History Tracking**: Maintain trails for visualization
+
+### 3. Country Lookup
+1. **ICAO Extraction**: Extract 24-bit ICAO address from aircraft data
+2. **Database Query**: Lookup country information in embedded SQLite database
+3. **Data Enrichment**: Add country, country code, and flag to aircraft state
+
+### 4. Data Distribution
+1. **REST API**: Provide aircraft data via HTTP endpoints
+2. **WebSocket Streaming**: Push low-latency updates to connected clients
+3. **Frontend Processing**: Update maps, tables, and visualizations
+4. **User Interface**: Display aircraft with country flags and details
+
+## Configuration System
+
+### Configuration Sources (Priority Order)
+1. Command-line flags (highest priority)
+2. Configuration file (JSON)
+3. Default values (lowest priority)
+
+### Configuration Structure
+```json
+{
+  "server": {
+    "host": "",        // Bind address (empty = all interfaces)
+    "port": 8080       // HTTP server port
+  },
+  "sources": [
+    {
+      "id": "unique-id",      // Source identifier
+      "name": "Display Name", // Human-readable name
+      "host": "hostname",     // Receiver hostname/IP
+      "port": 30005,          // Beast format port
+      "latitude": 51.4700,    // Receiver location
+      "longitude": -0.4600,   
+      "altitude": 50.0,       // Meters above sea level
+      "enabled": true         // Source enable/disable
+    }
+  ],
+  "settings": {
+    "history_limit": 500,    // Max trail points per aircraft
+    "stale_timeout": 60,     // Seconds before aircraft removed
+    "update_rate": 1         // WebSocket update frequency
+  },
+  "origin": {
+    "latitude": 51.4700,     // Map center point
+    "longitude": -0.4600,
+    "name": "Origin Name"
+  }
+}
+```
+
+## Performance Characteristics
+
+### Concurrency Model
+- **Goroutine per Source**: Each Beast client runs in separate goroutine
+- **Mutex-Protected Merger**: Thread-safe aircraft state management
+- **WebSocket Broadcasting**: Concurrent client update distribution
+- **Non-blocking I/O**: Asynchronous network operations
+
+### Memory Management
+- **Bounded History**: Configurable limits on historical data storage
+- **Automatic Cleanup**: Stale aircraft removal to prevent memory leaks
+- **Efficient Data Structures**: Maps for O(1) aircraft lookups
+- **Embedded Assets**: Static files bundled in binary
+
+### Scalability
+- **Multi-source Support**: Tested with 10+ concurrent receivers
+- **High Message Throughput**: Handles 1000+ messages/second per source
+- **Low-latency Updates**: Sub-second latency for aircraft updates
+- **Responsive Web UI**: Optimized for 100+ concurrent aircraft
+
+## Security Considerations
+
+### Network Security
+- **No Authentication Required**: Designed for trusted network environments
+- **Local Network Operation**: Intended for private receiver networks
+- **WebSocket Origin Checking**: Basic CORS protection
+
+### System Security
+- **Unprivileged Execution**: Runs as non-root user in production
+- **Filesystem Isolation**: Minimal file system access required
+- **Network Isolation**: Only requires outbound TCP to receivers
+- **Systemd Hardening**: Security features enabled in service file
+
+### Data Privacy
+- **Public ADS-B Data**: Only processes publicly broadcast aircraft data
+- **No Personal Information**: Aircraft tracking only, no passenger data
+- **Local Processing**: No data transmitted to external services
+- **Historical Limits**: Configurable data retention periods
+
+## External Resources
+
+### Official Standards
+- **ICAO Document 8585**: Designators for Aircraft Operating Agencies
+- **RTCA DO-260B**: ADS-B Message Formats and Protocols
+- **ITU-R M.1371-5**: Technical characteristics for universal ADS-B
+
+### Technology Dependencies
+- **Go Language**: https://golang.org/
+- **Leaflet.js**: https://leafletjs.com/ - Interactive maps
+- **Three.js**: https://threejs.org/ - 3D visualization
+- **Chart.js**: https://www.chartjs.org/ - Statistics charts
+- **SQLite**: https://www.sqlite.org/ - ICAO country database
+- **WebSocket Protocol**: RFC 6455
+
+### ADS-B Ecosystem
+- **dump1090**: https://github.com/antirez/dump1090 - SDR ADS-B decoder
+- **Beast Binary Format**: Mode S data interchange format
+- **FlightAware**: ADS-B network and data provider
+- **OpenSky Network**: Research-oriented ADS-B network
+
+## Development Guidelines
+
+### Code Organization
+- **Package per Component**: Clear separation of concerns
+- **Interface Abstractions**: Testable and mockable components
+- **Error Handling**: Comprehensive error reporting and recovery
+- **Documentation**: Extensive code comments and examples
+
+### Testing Strategy
+- **Unit Tests**: Component-level testing with mocks
+- **Integration Tests**: End-to-end data flow validation
+- **Performance Tests**: Load testing with simulated data
+- **Manual Testing**: Real-world receiver validation
+
+### Deployment Options
+- **Standalone Binary**: Single executable with embedded assets
+- **Debian Package**: Systemd service with configuration
+- **Docker Container**: Containerized deployment option
+- **Development Mode**: Hot-reload for frontend development
+
+---
+
+**SkyView Architecture** - Designed for reliability, performance, and extensibility in multi-source ADS-B tracking applications.
--- a/docs/CLAUDE.md
+++ b/docs/CLAUDE.md
@ -0,0 +1,39 @@
+# SkyView Project Guidelines
+
+## Documentation Requirements
+- We should always have an up to date document describing our architecture and features
+- Include links to any external resources we've used  
+- We should also always have an up to date README describing the project
+- Shell scripts should be validated with shellcheck
+- Always make sure the code is well documented with explanations for why and how a particular solution is selected
+
+## Development Principles
+- An overarching principle with all code is KISS, Keep It Simple Stupid
+- We do not want to create code that is more complicated than necessary
+- When changing code, always make sure to update any relevant tests
+- Use proper error handling - aviation applications need reliability
+
+## SkyView-Specific Guidelines
+
+### Architecture & Design
+- Multi-source ADS-B data fusion is the core feature - prioritize signal strength-based conflict resolution
+- Embedded resources (SQLite ICAO database, static assets) over external dependencies
+- Low-latency performance is critical - optimize for fast WebSocket updates
+- Support concurrent aircraft tracking (100+ aircraft should work smoothly)
+
+### Code Organization
+- Keep Go packages focused: beast parsing, modes decoding, merger, server, clients
+- Frontend should be modular: separate managers for aircraft, map, UI, websockets
+- Database operations should be fast (use indexes, avoid N+1 queries)
+
+### Performance Considerations
+- Beast binary parsing must handle high message rates (1000+ msg/sec per source)
+- WebSocket broadcasting should not block on slow clients
+- Memory usage should be bounded (configurable history limits)
+- CPU usage should remain low during normal operation
+
+### Documentation Maintenance
+- Always update docs/ARCHITECTURE.md when changing system design
+- README.md should stay current with features and usage
+- External resources (ICAO docs, ADS-B standards) should be linked in documentation
+- Country database updates should be straightforward (replace SQLite file)