{"id":40384677,"url":"https://github.com/punitarani/flights-tracker","last_synced_at":"2026-01-20T12:07:06.085Z","repository":{"id":317628923,"uuid":"1068149356","full_name":"punitarani/flights-tracker","owner":"punitarani","description":"Flights Tracker and Alerts","archived":false,"fork":false,"pushed_at":"2025-10-31T15:56:32.000Z","size":12812,"stargazers_count":10,"open_issues_count":11,"forks_count":2,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-31T17:29:56.569Z","etag":null,"topics":["flights-api","flights-data","flights-search"],"latest_commit_sha":null,"homepage":"https://graypane.com","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/punitarani.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-10-01T23:44:33.000Z","updated_at":"2025-10-21T09:42:53.000Z","dependencies_parsed_at":"2025-10-06T05:22:57.898Z","dependency_job_id":null,"html_url":"https://github.com/punitarani/flights-tracker","commit_stats":null,"previous_names":["punitarani/flights-tracker"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/punitarani/flights-tracker","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/punitarani%2Fflights-tracker","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/punitarani%2Fflights-tracker/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/punitarani%2Fflights-tracker/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/punitarani%2Fflights-tracker/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/punitarani","download_url":"https://codeload.github.com/punitarani/flights-tracker/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/punitarani%2Fflights-tracker/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28603386,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-20T12:01:53.233Z","status":"ssl_error","status_checked_at":"2026-01-20T12:01:46.545Z","response_time":117,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["flights-api","flights-data","flights-search"],"created_at":"2026-01-20T12:06:59.083Z","updated_at":"2026-01-20T12:07:06.075Z","avatar_url":"https://github.com/punitarani.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# GrayPane – Flight Search \u0026 Alerts\n\nGrayPane helps travelers check available flights, monitor price trends, plan upcoming trips, and create personalized alerts. The application is built with Next.js 15, React 19, Supabase authentication, a PostgreSQL database via Drizzle ORM, Apple MapKit visualizations, Tailwind CSS, and TypeScript.\n\n![Flight route planning interface showing a map from San Francisco to London](./data/demo-map.png)\n\n![Flight search filters UI with sliders and toggles](./data/demo-search-filters.png)\n\n![Flight search results with fare chart and itinerary details](./data/demo-search-results.png)\n\n## Key Features\n\n* Search for flights and review route availability in real time with comprehensive filtering.\n* Track fare changes and set alert thresholds for routes of interest.\n* Search award flight availability via seats.aero integration with async processing.\n* Plan itineraries with Supabase-backed user dashboards.\n* Create, edit, and manage alert rules with validation safeguards.\n* Automated alert processing with Cloudflare Workers and scheduled email notifications.\n* Explore airports with Apple MapKit maps and responsive Tailwind UI components.\n\n## Tech Stack\n\n* **Frontend:** Next.js 15, React 19, Tailwind CSS, Radix UI primitives, next-themes, Sonner, tRPC.\n* **Backend:** Next.js Server Actions, tRPC API layer, Supabase SSR client, Drizzle ORM.\n* **Workers:** Cloudflare Workers with Workflows and Queues for alert processing, fully decoupled from the Next.js app.\n* **Database:** PostgreSQL with prefixed ULID identifiers.\n* **Notifications:** Resend for email delivery, custom templates.\n* **Monitoring:** Sentry for error tracking and performance monitoring.\n* **Tooling:** TypeScript, Bun test runner with happy-dom, Biome formatter/linter, Bun runtime.\n\n## Prerequisites\n\n* Install [Bun](https://bun.sh/) for dependency management and scripts.\n* Copy `.env.example` to `.env.local` and populate the required variables validated by `@t3-oss/env-nextjs`.\n\n## Getting Started\n\n1. Install dependencies: `bun install`\n2. Run the development server: `bun run dev`\n3. Open `http://localhost:3000` to use Flights Tracker.\n\n## Available Scripts\n\n### Application\n\n* `bun run dev` – Start the Turbopack development server.\n* `bun run build` – Produce an optimized production bundle.\n* `bun start` – Serve the production build.\n\n### Testing\n\n* `bun test` – Execute all tests with Bun's built-in test runner.\n* `bun run test:watch` – Run tests in watch mode.\n* `bun run test:fli` – Run fli integration tests with extended timeout.\n* `bun run test:workers` – Run Cloudflare Worker tests (43 tests).\n* `bun run test:workers:watch` – Run worker tests in watch mode.\n\n### Code Quality\n\n* `bun run lint` – Check code style with Biome.\n* `bun run format` – Format the codebase with Biome.\n\n### Workers (Cloudflare)\n\n* `bun run worker:dev` – Start worker with local development server.\n* `bun run worker:deploy` – Deploy worker to Cloudflare.\n* `bun run worker:tail` – Stream live logs from production worker.\n* `bun run trigger:alerts` – Manually trigger alert processing (production).\n* `bun run trigger:alerts:local` – Manually trigger alert processing (local).\n\n## Database \u0026 Migrations\n\n* Schema definition: `src/db/schema.ts`\n* Database configuration: `drizzle.config.ts`\n* Migrations directory: `./migrations`\n* Commands:\n  * `bun run db:generate` – Generate migration files from schema changes.\n  * `bun run db:push` – Push schema updates directly to the development database.\n  * `bun run db:migrate` – Apply pending migrations.\n  * `bun run db:studio` – Open Drizzle Studio for database exploration.\n\n## Architecture Overview\n\n### API Layer\n\n**tRPC Architecture**: End-to-end type-safe API with:\n\n* Server routers in `src/server/routers/` for alerts, flights, airports, and seats.aero\n* React Query integration via `@trpc/react-query` for client-side data fetching\n* Automatic error handling and validation with Zod schemas\n* Real-time subscriptions support\n\n### Database Layer\n\nDrizzle ORM manages PostgreSQL entities:\n\n* Core tables: `airport`, `airline`, `alert` with JSONB filters\n* Workers tables: `seats_aero_search_request`, `seats_aero_availability_trip`\n* Notification table for email tracking and rate limiting\n\n### Authentication \u0026 Middleware\n\nSupabase handles authentication with SSR support. Middleware in `src/middleware.ts` to validate sessions and enforce public-route access rules.\n\n### Business Logic\n\n**Core Services**:\n\n* `src/core/alerts-service.ts` - High-level alert business logic\n* `src/core/alerts-db.ts` - Database operations for alerts\n* `src/core/seats-aero.db.ts` - Seats.aero data management\n* `src/core/filters.ts` - Zod schemas for alert filters (versioned)\n* `src/lib/notifications/` - Email templates and delivery system\n\n**Worker Adapters**:\n\n* `src/workers/adapters/` - Thin wrappers around core services\n* `src/workers/utils/` - Worker-specific utilities (logger, Sentry, Supabase client wrappers)\n\n### Alert Processing (Cloudflare Workers)\n\nAutomated alert processing runs on Cloudflare Workers with:\n\n* **Cron Triggers**: Every 6 hours (00:00, 06:00, 12:00, 18:00 UTC)\n* **Workflows**: Durable execution with automatic retries and state persistence\n* **Queues**: Process up to 10 users concurrently with auto-scaling\n* **Email Scheduling**: Sends daily emails between 6-9 PM UTC, max once per 24 hours\n* **Monitoring**: Full Sentry integration for error tracking and performance monitoring\n* **Testing**: Comprehensive test suite with 43 passing tests\n* **Performance**: Optimized with parallel async operations throughout\n\nSee `docs/workflows.md` for complete deployment and monitoring guide.\n\n### UI Components\n\nReusable components reside in `src/components/ui`, while custom features like `airport-search` and `airport-map` integrate Apple MapKit and Tailwind styling. Path alias `@/*` maps to `./src/*` for cleaner imports.\n\n## Environment Variables\n\n### Next.js Application\n\n* `DATABASE_URL` – PostgreSQL connection string.\n* `NEXT_PUBLIC_SUPABASE_URL` – Supabase project URL.\n* `NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY` – Supabase anon key.\n* `SUPABASE_SECRET_KEY` – Supabase service role key.\n* `NEXT_PUBLIC_MAPKIT_TOKEN` – Apple MapKit JS token.\n* `WORKER_URL` – Cloudflare Workers URL for seats.aero searches.\n* `WORKER_API_KEY` – Authentication key for worker endpoints.\n\n### Cloudflare Workers\n\n* `DATABASE_URL` – PostgreSQL connection string.\n* `RESEND_API_KEY` – Resend email service API key.\n* `SUPABASE_URL` – Supabase project URL.\n* `SUPABASE_SERVICE_ROLE_KEY` – Supabase service role key.\n* `SEATS_AERO_API_KEY` – Seats.aero API key.\n* `WORKER_API_KEY` – API key for authenticating manual triggers.\n* `SENTRY_DSN` – Sentry project DSN (optional but recommended).\n\n## Testing\n\n### Application Tests\n\nTests run with Bun's built-in test runner in a happy-dom environment. Global setup, mocks, and database stubs are configured in `src/test/setup.ts`.\n\n### Worker Tests\n\nComprehensive test suite for Cloudflare Workers with 43 passing tests covering:\n\n* Utils (logger, user fetching, flights search, sentry)\n* Adapters (alerts-db, alert-processing)\n* Workflows (check-flight-alerts, process-flight-alerts)\n* Handlers (scheduled, queue, fetch)\n* E2E flow validation\n\nRun with `bun run test:workers` - all tests execute in under 100ms without requiring Cloudflare Workers runtime.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpunitarani%2Fflights-tracker","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpunitarani%2Fflights-tracker","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpunitarani%2Fflights-tracker/lists"}