CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What this project is

BirdGO is an offline-first SPA that works like PokémonGO but for real birds. The user taps to listen; BirdNET (via TensorFlow.js) classifies bird sounds locally in the browser; identified species go into a local collection. No audio or data is sent to any server. Online accounts and leaderboards are a planned future feature.

Commands

All tasks run via Deno. Use deno task instead of npm run.

deno task dev          # start dev server
deno task build        # production build
deno task preview      # preview production build
deno task check        # svelte-kit sync + svelte-check (type checking)
deno task lint         # ESLint
deno task test         # run all Playwright e2e tests
deno fmt               # format (spaces, double quotes, includes Svelte components)

Run a single e2e test file:

deno run -A npm:playwright test src/routes/path/to/page.svelte.e2e.ts

Code style

• TypeScript everywhere, full types. No any, no type assertions unless truly unavoidable.
• Nested CSS inside <style> blocks. Use element and hierarchy selectors (nav a, section > h2) over classes wherever the HTML structure makes the selector unambiguous. Classes only when hierarchy isn't enough.
• Semantic HTML. Use <main>, <nav>, <section>, <article>, <button>, <dialog>, etc. correctly.
• No premature component extraction. Keep markup inline until a piece is genuinely reused in two or more places. A component for one caller is noise.
• Simplest possible implementation. No abstractions for hypothetical futures. Three similar lines beat a premature helper.
• Svelte 5 runes only. $state(), $derived(), $effect(), $props(). The Options API is disabled globally in svelte.config.js.

Architecture

This is a SvelteKit SPA using Svelte 5 with Deno as the runtime and package manager. SvelteKit is used for its component model, routing, and build tooling — not for SSR. All data lives in the browser (IndexedDB).

Key layers

• src/routes/ — file-based routing. +page.svelte is the page, +layout.svelte wraps child routes.
• src/lib/ — shared code only. Accessed via the $lib alias. Subdivide as needed: $lib/audio/, $lib/db/, $lib/model/.
• Audio pipeline — Web Audio API → BirdNET (TensorFlow.js TFJS model) → species result. Runs entirely client-side.
• Persistence — IndexedDB for the bird collection and user state. No backend.
• Offline — PWA / service worker (not yet implemented).

Config files

• deno.json — Deno tasks and formatter config (fmt-component unstable flag enables Svelte formatting).
• package.json — npm-compatible dependency declarations consumed by Deno's npm compatibility layer.
• svelte.config.js — SvelteKit adapter (adapter-auto) and runes enforcement.
• playwright.config.ts — e2e tests run against a production build (port 4173), not the dev server. Test files use the .e2e.{ts,js} extension, collocated with their routes.
• tsconfig.json — extends .svelte-kit/tsconfig.json; strict mode enabled.

Environment

DENO_DIR is set to /home/developer/.cache/deno in .claude/settings.json (the default /deno-dir/ is not writable). This is applied automatically — no manual export needed.