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.