Ole-Morten Duesund
37c4fa2b57
- Implement comprehensive database package with versioned migrations - Add skyview-data CLI tool for managing aviation reference data - Integrate database with merger for real-time aircraft history persistence - Support OurAirports and OpenFlights data sources (runtime loading) - Add systemd timer for automated database updates - Fix transaction-based bulk loading for 2400% performance improvement - Add callsign enhancement system with airline/airport lookups - Update Debian packaging with database directory and permissions Database features: - Aircraft position history with configurable retention - External aviation data loading (airlines, airports) - Callsign parsing and enhancement - API client for external lookups (OpenSky, etc.) - Privacy mode for complete offline operation CLI commands: - skyview-data status: Show database statistics - skyview-data update: Load aviation reference data - skyview-data list: Show available data sources - skyview-data clear: Remove specific data sources 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
107 lines
No EOL
4.6 KiB
Markdown
107 lines
No EOL
4.6 KiB
Markdown
# SkyView Development Guidelines
|
|
|
|
This document outlines coding standards, architectural principles, and development practices for the SkyView ADS-B aircraft tracking system.
|
|
|
|
## Core Development Principles
|
|
|
|
### KISS Principle
|
|
- **Keep It Simple Stupid** - avoid unnecessary complexity
|
|
- Choose straightforward solutions over clever ones
|
|
- Prioritize readability and maintainability
|
|
- Don't over-engineer features
|
|
|
|
### Quality Standards
|
|
- **Error Handling**: Aviation applications require reliability - implement comprehensive error handling
|
|
- **Testing**: Always update relevant tests when modifying code
|
|
- **Documentation**: Code must be well-documented with explanations of WHY, not just what
|
|
- **Validation**: Shell scripts must pass `shellcheck` validation
|
|
|
|
## SkyView Architecture Guidelines
|
|
|
|
### Core Features
|
|
- **Multi-source Data Fusion**: Primary feature - use signal strength for conflict resolution
|
|
- **Embedded Resources**: Prefer embedded SQLite ICAO database and static assets over external dependencies
|
|
- **Real-time Performance**: Optimize for low-latency WebSocket updates
|
|
- **Scalability**: Support 100+ concurrent aircraft tracking smoothly
|
|
|
|
### Code Organization
|
|
|
|
#### Backend (Go)
|
|
- **beast**: Raw ADS-B message parsing from TCP streams
|
|
- **modes**: Mode S/ADS-B message decoding and aircraft data extraction
|
|
- **merger**: Multi-source data fusion with conflict resolution
|
|
- **server**: HTTP/WebSocket server with API endpoints
|
|
- **client**: Connection management for Beast format sources
|
|
|
|
#### Frontend (JavaScript)
|
|
- **aircraft-manager**: Aircraft state management and display logic
|
|
- **map-manager**: Leaflet map integration and geographic operations
|
|
- **ui-manager**: User interface controls and event handling
|
|
- **websocket**: Real-time data streaming from server
|
|
|
|
### Performance Requirements
|
|
|
|
#### Message Processing
|
|
- **High Throughput**: Handle 1000+ messages/second per source
|
|
- **Non-blocking**: WebSocket broadcasting must not block on slow clients
|
|
- **Memory Bounds**: Configurable history limits prevent unbounded growth
|
|
- **Low CPU**: Maintain efficient operation under normal load
|
|
|
|
#### Database Operations
|
|
- **Indexing**: Use proper indexes to avoid N+1 queries
|
|
- **Fast Lookups**: ICAO country resolution must be efficient
|
|
- **Bounded History**: Implement automatic cleanup of stale data
|
|
|
|
## Documentation Standards
|
|
|
|
### Required Documentation
|
|
- **Architecture**: Keep `docs/ARCHITECTURE.md` current with system design changes
|
|
- **User Guide**: Maintain up-to-date `README.md` with features and usage instructions
|
|
- **External References**: Link to ICAO docs, ADS-B standards, and other resources
|
|
- **Code Comments**: Explain complex algorithms, especially CPR decoding and data fusion logic
|
|
|
|
### Documentation Updates
|
|
- Update architecture docs BEFORE merging structural changes
|
|
- Include usage examples for new features
|
|
- Document configuration options and their effects
|
|
- Explain performance implications of architectural decisions
|
|
|
|
## Repository and Tooling
|
|
|
|
### Version Control
|
|
- **Repository**: This project uses Forgejo, not GitHub
|
|
- **Tooling Preference**:
|
|
1. `forgejo-mcp` (Model Context Protocol integration)
|
|
2. `fj` CLI client (fallback for operations not supported by MCP)
|
|
- **Prohibited Tools**: Do not use `gh` or other GitHub-oriented tools
|
|
|
|
### Release Management
|
|
- Use semantic versioning (e.g., v0.0.3)
|
|
- Include Debian package builds in releases
|
|
- Provide comprehensive release notes with feature descriptions
|
|
- Tag releases properly for easy version tracking
|
|
|
|
## Aviation Domain Considerations
|
|
|
|
### Data Accuracy
|
|
- Position validation is critical - implement impossible movement detection
|
|
- Handle CPR decoding errors gracefully with recovery mechanisms
|
|
- Validate aircraft categories and transponder information
|
|
- Implement rate-limited logging for validation errors
|
|
|
|
### Regulatory Compliance
|
|
- Follow ICAO standards for ADS-B message interpretation
|
|
- Respect aircraft privacy considerations in data display
|
|
- Ensure accurate country identification from ICAO allocation tables
|
|
- Document deviation from standards when necessary
|
|
|
|
### User Safety
|
|
- Never display obviously incorrect aircraft positions
|
|
- Implement reasonable defaults for safety-critical features
|
|
- Provide clear visual indicators for data quality and source reliability
|
|
- Handle edge cases that could confuse air traffic interpretation
|
|
|
|
---
|
|
|
|
These guidelines ensure SkyView remains reliable, maintainable, and suitable for aviation use while supporting continued development and enhancement.
|
|
- All future changes to the UX should keep in mind a gradual move to a mobile friendly design, but not at the cost of a working and useful UI for non-mobile clients. |