ha-airspace: Instructions file for Claude Code

CLAUDE.md

Project-specific guidance for Claude Code working on ha-airspace.

Always read DESIGN.md first — it's the source of truth for architecture, scope, and phase boundaries. This file covers conventions and workflow.

---

Project at a glance

ha-airspace is a Python service that consumes aircraft.json from one or more ADS-B receivers (dump1090, readsb, dump978-fa), enriches with reference databases, applies tagging/alert rules, and publishes to MQTT for Home Assistant consumption.

Distribution targets: HA add-on (primary), Docker image, pip package — same codebase.

Non-goals to remember: not a feeder, not a replacement for dump1090, not a website, not a HACS integration. If a change pushes toward any of those, stop and check in.

---

Tech stack

• Python 3.12+. Use modern syntax (match, | unions, Self, parameterized generics without typing.).
• Async-first. asyncio throughout. Receivers, MQTT, DB refresh — all async. No threading except for CPU-bound DB parsing in an executor.
• httpx for HTTP (async, supports HTTP/2, sane timeouts).
• aiomqtt for MQTT (asyncio-native paho wrapper).
• pydantic v2 for config schema validation. Strict mode; reject unknown fields with helpful errors.
• structlog for logging. JSON output in production, console renderer in dev.
• uv for dependency management and virtualenvs. pyproject.toml is canonical; no requirements.txt.
• ruff for lint + format (replaces black, isort, flake8).
• pytest + pytest-asyncio for tests.
• mypy --strict for type checking.

Don't introduce new dependencies without flagging it. The runtime footprint matters — this ships as a HA add-on and people run it on Raspberry Pis.

---

Code conventions

Style

• Format and lint with ruff. The repo's pyproject.toml is the source of truth — don't override locally.
• Line length: 100. Not 80, not 120.
• Type hints on every function signature, including tests. Any is a code smell; if you reach for it, leave a comment explaining why.
• from __future__ import annotations at the top of every module. Forward references everywhere, no exceptions.
• Imports: stdlib, third-party, first-party — three groups separated by blank lines. ruff enforces this.
• Prefer dataclasses (frozen where possible) over plain classes for data containers. Use pydantic.BaseModel only at config boundaries where validation matters.