106 lines
No EOL
4.6 KiB
Markdown
106 lines
No EOL
4.6 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Project Overview
|
|
|
|
This is an Elixir Phoenix LiveView application that serves as a real-time APRS (Automatic Packet Reporting System) tracker and visualizer. It connects to the APRS-IS network to receive live amateur radio packets and displays them on an interactive map interface.
|
|
|
|
## Development Commands
|
|
|
|
### Setup
|
|
- `mix setup` - Complete project setup (deps.get + ecto.setup)
|
|
- `mix deps.get` - Install dependencies
|
|
- `mix ecto.setup` - Create database, run migrations, and seed data
|
|
- `mix ecto.reset` - Drop and recreate database
|
|
- `mix phx.server` - Start Phoenix server (http://localhost:4000)
|
|
- `iex -S mix phx.server` - Start server in interactive Elixir shell
|
|
|
|
### Testing
|
|
- `mix test` - Run full test suite
|
|
- `mix test --stale` - Run only tests affected by code changes
|
|
- `mix test.watch` - Continuous testing with file watching
|
|
- `mix test --cover` - Generate test coverage reports
|
|
|
|
### Code Quality
|
|
- `mix format` - Format code according to .formatter.exs
|
|
- `mix credo` - Static code analysis and style checking
|
|
- `mix dialyzer` - Static type analysis (must run and fix errors/warnings)
|
|
- `mix sobelow` - Security vulnerability scanning
|
|
- **IMPORTANT**: Always run `mix format` before considering any task complete
|
|
|
|
### Assets (No Node.js)
|
|
- `mix assets.deploy` - Build and minify frontend assets (Tailwind CSS + ESBuild)
|
|
- Phoenix uses ESBuild directly without Node.js package managers
|
|
|
|
## Architecture
|
|
|
|
### Core Components
|
|
- **Aprsme.AprsIsConnection** - TCP connection to APRS-IS network with reconnection logic
|
|
- **Aprsme.PacketConsumer** - Processes incoming APRS packets using GenStage pipeline
|
|
- **Aprsme.Packet** - Database schema for APRS packets with PostGIS geographic data
|
|
- **AprsmeWeb.MapLive.Index** - Main real-time map interface using Phoenix LiveView
|
|
- **Aprsme.Workers.PacketCleanupWorker** - Oban background job for data cleanup
|
|
|
|
### Data Flow
|
|
1. APRS-IS connection receives packets via TCP
|
|
2. PacketConsumer processes packets through GenStage pipeline
|
|
3. Packets stored in PostgreSQL with PostGIS geographic indexing
|
|
4. LiveView broadcasts real-time updates to connected clients via PubSub
|
|
5. Background workers handle cleanup and maintenance tasks
|
|
|
|
### Key Dependencies
|
|
- Phoenix LiveView for real-time UI without JavaScript
|
|
- PostGIS for geographic data storage and spatial queries
|
|
- Oban for background job processing
|
|
- GenStage for packet processing pipelines
|
|
- Tailwind CSS + ESBuild for frontend assets (no Node.js)
|
|
|
|
## Test-Driven Development
|
|
|
|
**MANDATORY**: Follow strict test-driven development (TDD) practices:
|
|
|
|
1. **Red Phase**: Write failing tests first before implementing any functionality
|
|
2. **Green Phase**: Write minimal code to make tests pass
|
|
3. **Refactor Phase**: Improve code while keeping tests green
|
|
|
|
### TDD Workflow
|
|
- Always write tests before implementing new features or fixing bugs
|
|
- Start with the simplest failing test case
|
|
- Write only enough code to make the test pass
|
|
- Refactor with confidence knowing tests will catch regressions
|
|
- Run `mix test` frequently during development
|
|
- Use `mix test.watch` for continuous feedback
|
|
|
|
### Testing Patterns
|
|
|
|
Tests use comprehensive mocking to prevent external connections:
|
|
- APRS-IS connections are mocked in test environment
|
|
- Database uses sandbox mode for isolation
|
|
- External API calls mocked with Mox library
|
|
- Write unit tests for business logic, integration tests for workflows
|
|
- Test edge cases and error conditions thoroughly
|
|
- Maintain high test coverage with `mix test --cover`
|
|
|
|
## Code Style Guidelines
|
|
|
|
- **CRITICAL**: Never write production code without tests first
|
|
- Use LiveView for UI interactions, minimize JavaScript
|
|
- Prefer pattern matching over if/case statements
|
|
- Follow idiomatic Elixir conventions
|
|
- Run `mix format` before committing
|
|
- Address any compiler warnings
|
|
- Run `mix dialyzer` and fix all errors/warnings
|
|
- **MANDATORY**: Run `mix compile --warnings-as-errors` and ensure it passes before considering any task complete
|
|
- Use function composition over nested conditionals
|
|
- Write descriptive test names that explain behavior
|
|
|
|
## Web Testing
|
|
|
|
- **MANDATORY**: When viewing any website or web application, always use Puppeteer to take screenshots and interact with the page
|
|
- Use `mcp__puppeteer__puppeteer_navigate`, `mcp__puppeteer__puppeteer_screenshot`, and other Puppeteer tools
|
|
- This ensures accurate visual feedback and proper testing of the user interface
|
|
|
|
## Deployment
|
|
|
|
The application supports Kubernetes deployment with manifests in `k8s/` directory and GitHub Actions CI/CD pipeline. Database migrations run automatically via init containers. |