build-small-hackathon/rarebirds

rarebirds

rarebirds is a two-track project:

1. 1.A Gradio/Gemma workspace for experimenting with sub-32B rarity classifiers.
2. 2.An iPhone app that tells a user when rare aircraft are flying near them and sends push notifications.

The product should treat the model and the mobile app as separate concerns, but Gemma is part of the alert pipeline: it should quickly classify whether a live aircraft looks rare from the aircraft state, instead of forcing every sighting through slow database searches. The backend still owns geospatial matching, cooldowns, and APNs delivery.

Repository Layout

backend/    Server-side aircraft polling, rare-aircraft matching, and APNs fanout.
data/       Rule lists and seed data used by the backend.
docs/       Architecture notes and decisions.
ios/        Native SwiftUI iPhone app workspace notes.
model/      Gemma 4 tuning and inference workspace.

Product Shape

The first version should answer one question quickly: "Is something rare near me right now?"

Core flows:

• —User grants location permission and notification permission.
• —User sets an alert radius, aircraft categories, and quiet hours.
• —Backend polls or streams aircraft positions for active user regions.
• —Backend asks Gemma to score whether candidate aircraft are rare, with deterministic rules as guardrails.
• —Backend sends an APNs notification when a new match crosses the user's threshold.
• —App shows a current nearby list, aircraft details, and recent alert history.

Current Data Source Assumptions

• —OpenSky is useful for research and non-commercial prototypes.
• —ADSB Exchange has strong live ADS-B coverage and commercial API options.
• —FlightAware AeroAPI is better when flight status, schedules, or richer commercial metadata matter.

See docs/architecture.md for the initial design.