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

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.