From 61e80f67353d25fe8d8719c52f4a6ca0e03ba960 Mon Sep 17 00:00:00 2001 From: Ole-Morten Duesund Date: Sun, 24 Aug 2025 21:32:30 +0200 Subject: [PATCH] Rewrite CLAUDE.md for improved clarity and completeness MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 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 --- CLAUDE.md | 129 +++++++++++++++++++++++++++++++++++++++++------------- 1 file changed, 98 insertions(+), 31 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 336d043..4b70eb8 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -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) \ No newline at end of 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. \ No newline at end of file