olemd/skyview
1
0
Fork 0
Code Issues 12 Pull requests Projects Releases 11 Packages Wiki Activity Actions

Rewrite CLAUDE.md for improved clarity and completeness

Browse source 
- Restructured into logical sections with clear hierarchy
- Added comprehensive development principles and quality standards
- Detailed code organization for both backend (Go) and frontend (JS)
- Explicit performance requirements with specific metrics
- Clear documentation standards and maintenance responsibilities
- Aviation domain considerations for safety and regulatory compliance
- Repository tooling guidelines emphasizing Forgejo over GitHub tools
- Added release management and version control best practices

Now serves as a complete development handbook for the SkyView project.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Ole-Morten Duesund 2025-08-24 21:32:30 +02:00
commit 61e80f6735
1 changed files with 100 additions and 33 deletions
Download patch file Download diff file Expand all files Collapse all files

129
CLAUDE.md
View file

@ -1,39 +1,106 @@
# SkyView Project Guidelines
# SkyView Development 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
This document outlines coding standards, architectural principles, and development practices for the SkyView ADS-B aircraft tracking system.
## 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
## Core Development Principles
## SkyView-Specific Guidelines
### KISS Principle
- **Keep It Simple Stupid** - avoid unnecessary complexity
- Choose straightforward solutions over clever ones
- Prioritize readability and maintainability
- Don't over-engineer features
### 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)
### 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
- 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
#### 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
### 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)
#### 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.2)
- 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.