skyview/CLAUDE.md

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

Build System and Development Workflow

Make Targets

The project uses a comprehensive Makefile for build automation:

Core Build Commands

• make build - Build main skyview binary
• make build-all - Build all binaries (skyview, beast-dump, skyview-data)
• make clean - Clean build artifacts
• make dev - Run in development mode
• make run - Build and run the main binary

Code Quality Commands

• make test - Run all tests
• make lint - Run golangci-lint (if available)
• make format - Format code with go fmt
• make vet - Run go vet static analysis
• make check - Run all quality checks (format, vet, lint, test)

Package Management

• make deb - Build Debian package
• make deb-install - Install Debian package (requires sudo)
• make deb-remove - Remove installed Debian package (requires sudo)
• make deb-clean - Clean Debian build artifacts

Container Support

• make docker-build - Build Docker image
• make podman-build - Build Podman image (preferred for rootless containers)

Required Build Environment

• CGO_ENABLED=1: Required for SQLite3 database support
• Go Modules: Use make install-deps to ensure dependencies are current
• Version Injection: Version is automatically injected from git tags

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

Command Line Tools

• skyview: Main server application
• beast-dump: Raw ADS-B message debugging utility
• skyview-data: Database management and status tools

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
• SQLite Integration: Use embedded SQLite with CGO support

Development Process

Pre-commit Checks

Always run before committing:

make check  # Runs format, vet, lint, and test

Testing Strategy

• Unit Tests: Test individual components and functions
• Integration Tests: Test component interactions
• Performance Tests: Validate throughput requirements
• Manual Testing: Verify aviation-specific scenarios

Continuous Integration

• All code changes must pass make check
• Debian packages must build successfully
• Container builds must complete without errors

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
• Database Schema: Document database structure in docs/DATABASE.md
• 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
• Version Updates: When creating releases, update ALL version references:
  • Web pages and HTML templates
  • Man pages and documentation
  • Debian package control files
  • Configuration examples

Container Strategy

• Prefer Podman: Use rootless Podman over Docker when possible
• Build Format: Use BUILDAH_FORMAT=docker for Podman containers to support health status
• Multi-stage Builds: Optimize container size with proper layering

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

User Experience Guidelines

Mobile Responsiveness

• All future UX changes should consider mobile-friendly design
• Never sacrifice desktop/non-mobile functionality for mobile compatibility
• Implement progressive enhancement where possible
• Test on multiple screen sizes and orientations

Performance Expectations

• Real-time updates must remain smooth with 100+ aircraft
• Map interactions should be responsive even under high load
• Database queries must complete within acceptable timeouts
• WebSocket connections should handle network interruptions gracefully

Security and Safety

Process Management

• Critical: Never terminate processes using xargs
• Always verify process identity before stopping/killing
• Exercise extreme caution with system-level operations

Data Validation

• Validate all input data, especially from external ADS-B sources
• Implement rate limiting for external data sources
• Sanitize user inputs in web interface
• Log security-relevant events appropriately

---

These guidelines ensure SkyView remains reliable, maintainable, and suitable for aviation use while supporting continued development and enhancement. All development work should follow these standards to maintain code quality and system reliability.