Bird ID

Languages: English | 简体中文

Note: The English documentation is the canonical source of truth. If translations differ, follow the English version.

Background

This repository was built with AI agents and agent skills harnessed around Architecture Compiler, a deterministic compiler that turns constraints into explicit, reviewable architectural decisions with clear trade-offs and cost impact, grounded in a curated registry of 180+ design patterns.

The work started with Claude Code using Superpowers skills to brainstorm with the user about the functional requirements and capture the initial concept in [[redacted]-bird-id-webapp-initial-draft.md]([redacted]-bird-id-webapp-initial-draft.md).

Claude Code then used the Architecture Compiler skills to generate the approved architecture artifacts under docs/architecture/ and the implementation plan in [docs/plans/[redacted]-bird-id-implementation.md](docs/plans/%5Bredacted%5D-bird-id-implementation.md). Adversarial review findings were addressed in the implementation plan before implementation began.

Implementation then proceeded against that approved architecture and plan, using both Architecture Compiler skills and Superpowers skills to keep the work aligned with the architectural contract.

For sensitivity reasons, certain dates, names, and related identifying details in the documentation have been redacted.

Everything below, and the rest of the documentation, was written by AI agents.

Application

A SaaS web app where photographers upload bird photos and Claude AI identifies the species. Results are stored in a per-user history and species sighting log.

Features

• Upload bird photos (drag-and-drop or click to select)
• Claude claude-sonnet-4-6 vision model identifies species, confidence, and count
• Async identification with polling — result URL survives page reload
• Per-user history and species sighting log
• Free tier: 10 identifications/month (enforced via Redis)
• Pro tier: unlimited identifications
• Auth0 Universal Login (Google OAuth included)

Architecture

Design Patterns Applied

Full architecture specification: docs/architecture/architecture.yaml

Project Structure

arch-compiler-ai-harness-in-action/
├── backend/                      # FastAPI application
│   ├── app/
│   │   ├── main.py               # App entry point, CORS, API versioning middleware
│   │   ├── config.py             # Pydantic settings (env vars)
│   │   ├── database.py           # Async SQLAlchemy engine (asyncpg, SSL)
│   │   ├── auth.py               # Auth0 JWKS validation, in-process cache, user provisioning
│   │   ├── schemas.py            # Pydantic response models
│   │   ├── telemetry.py          # OpenTelemetry setup + golden-signal meters
│   │   ├── feature_flags.py      # Config-file feature flags (kill switch)
│   │   ├── redis_client.py       # Async Redis singleton
│   │   ├── resilience.py         # CircuitBreaker (3-state) + with_retry (exponential jitter)
│   │   ├── models/
│   │   │   ├── user.py           # User (id, auth0_sub, email, plan)
│   │   │   ├── image.py          # Image (storage_key, file_size_bytes)
│   │   │   └── identification.py # Identification + BirdDetected
│   │   ├── routers/
│   │   │   ├── identify.py       # POST /identify — upload, rate-limit, background task
│   │   │   └── history.py        # GET /history, /birds, /user/plan, /billing/upgrade
│   │   ├── services/
│   │   │   ├── claude.py         # Claude vision inference (asyncio.to_thread)
│   │   │   └── storage.py        # Cloudflare R2 via boto3 (asyncio.to_thread)
│   │   ├── middleware/
│   │   │   └── rate_limit.py     # Redis sliding-TTL rate limiter
│   │   └── scripts/
│   │       └── cleanup_old_records.py  # 365-day cascade delete
│   ├── tests/                    # 34 tests (pytest-asyncio, savepoint rollback isolation)
│   ├── feature_flags.json        # Runtime feature flag values
│   ├── Dockerfile                # python:3.12-slim, uvicorn 2 workers
│   └── railway.toml              # Railway deploy config
├── frontend/                     # Next.js 16 application
│   ├── app/
│   │   ├── page.tsx              # Upload page (drag-drop, 429 error handling)
│   │   ├── identify/[id]/        # Polling page (spinner → result, URL-based ID)
│   │   ├── history/              # History list (paginated) + detail
│   │   └── species/              # Species log + per-species sightings
│   ├── components/
│   │   ├── AuthGuard.tsx         # Auth0 gate, wires getAccessTokenSilently to API client
│   │   ├── Providers.tsx         # Auth0Provider (client component, SSR-safe)
│   │   ├── UploadZone.tsx        # Drag-and-drop + keyboard accessible file picker
│   │   └── IdentificationResult.tsx  # Bird list with confidence and count
│   ├── hooks/
│   │   └── usePolling.ts         # 2s interval, 60s timeout ceiling, React 19 safe
│   ├── lib/
│   │   └── api.ts                # Typed API client with 401 → token refresh → retry
│   └── vercel.json               # Immutable CDN headers + security headers
├── docs/
│   ├── architecture/
│   │   ├── architecture.yaml     # Approved architecture specification
│   │   └── patterns/             # 24 selected design pattern manifests
│   ├── adrs/                     # Architecture Decision Records
│   ├── runbooks/                 # Incident runbooks
│   └── plans/                    # Implementation plan
└── docker-compose.yml            # Local postgres + redis for development

Local Development

Prerequisites

• Docker Desktop (for local postgres + redis)
• Python 3.12
• Node.js 20.9+

Backend

# 1. Start local postgres + redis
docker compose up -d

# 2. Set up Python virtualenv
cd backend
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e ".[dev]"

# 3. Copy and fill in env vars
cp ../.env.example .env
# Edit .env — see Environment Variables section below

# 4. Run database migrations
alembic upgrade head

# 5. Start the API server
uvicorn app.main:app --reload
# API available at http://localhost:8000

Frontend

cd frontend
npm install

# Copy and fill in env vars
cp .env.local.example .env.local
# Edit .env.local — see Environment Variables section below

npm run dev
# App available at http://localhost:3000

Optional frontend verification:

npm run lint
npm run build

Running Tests

Tests inject dummy credentials for all external services (Anthropic, Auth0, R2). The only real dependency is local Docker postgres + redis.

# Start local postgres + redis (if not already running)
docker compose up -d

cd backend

# Run all tests
.venv/bin/python -m pytest tests/ -v

# Silence OpenTelemetry export warnings (no local collector needed)
OTEL_SDK_DISABLED=true .venv/bin/python -m pytest tests/ -v

Expected: 34 passed

The warnings Failed to export metrics to localhost:4317 are harmless — they appear when no OpenTelemetry collector is running locally and can be silenced with OTEL_SDK_DISABLED=true. The test fixture creates birdid_test automatically if it does not already exist.

Environment Variables

Backend (backend/.env)

Frontend (frontend/.env.local)

Auth0 Setup

1. Create a Single Page Application in Auth0 dashboard

• Allowed Callback URLs: http://localhost:3000/
• Allowed Logout URLs: http://localhost:3000/
• Allowed Web Origins: http://localhost:3000

1. Create an API in Auth0 dashboard

• Identifier: https://api.bird-id.app (or your own)

1. Enable Google social connection (optional, free)

Feature Flags

Edit backend/feature_flags.json to toggle features without a deploy:

{
  "claude_identification_enabled": true,
  "pro_plan_enabled": false
}

Deployment

Backend → Railway

1. Connect your GitHub repo to Railway
2. Set root directory to backend/
3. Railway picks up backend/Dockerfile automatically
4. Add all backend environment variables in Railway's dashboard
5. Add a Redis service in Railway and link it
6. Rolling deploy is configured via railway.toml — Railway rolls back automatically on failed health checks

Frontend → Vercel

1. Connect your GitHub repo to Vercel
2. Set root directory to frontend/
3. Add all NEXT_PUBLIC_* environment variables in Vercel's dashboard
4. vercel.json configures immutable CDN caching for /_next/static/* and security headers on all routes

API Reference

All endpoints require Authorization: Bearer <token> except /health.

Response header API-Version: 2026-01-01 is included on every response.

Architecture Decision Records

ADR-001: Auth0 for OIDC Authentication

Date: [redacted] | Status: Accepted

Context: Need user authentication. Options: self-hosted JWT, Auth0, Clerk.

Decision: Auth0 Universal Login with OIDC / PKCE authorization_code flow.

Consequences:

• ✅ No password storage or session management in our code
• ✅ Social login (Google) included at zero extra cost; 7,500 MAU free
• ✅ PKCE enforced automatically by Auth0 React SDK
• ❌ Vendor dependency; token migration required if switching providers

ADR-002: Async Polling over WebSockets

Date: [redacted] | Status: Accepted

Context: Claude vision calls take 3–15 seconds. Blocking HTTP causes timeouts on Vercel (10s limit).

Decision: POST /identify returns 202 immediately; client polls GET /identify/{id} every 2 seconds. identification_id stored in the URL so polling survives page reload.

Consequences:

• ✅ No persistent connection layer (Redis pub/sub, Socket.io)
• ✅ identification_id in URL — user can bookmark or reopen a result after logging in
• ❌ Higher request count vs WebSocket (negligible at this scale)

ADR-003: Cloudflare R2 for Image Storage

Date: [redacted] | Status: Accepted

Context: Need object storage for uploaded bird images (image-heavy workload).

Decision: Cloudflare R2 with S3-compatible API.

Consequences:

• ✅ $0 egress cost (vs S3 ~$0.09/GB) — critical for image workloads
• ✅ boto3 works unchanged via endpoint override
• ❌ Slightly less tooling ecosystem than S3

Runbooks

Runbook: High Identification Failure Rate

Severity: 2 — degraded (identifications fail; app accessible)

Detection

• Railway logs: filter for "status": "failed" or error_message
• Feature flag check: cat backend/feature_flags.json

Diagnosis

1. Check Railway logs for "Circuit open" → circuit breaker tripped
2. Check https://status.anthropic.com → Claude API outage?
3. Run: grep -c '"status":"failed"' railway_logs.txt for failure rate

Recovery

• If Claude is down: set claude_identification_enabled: false in feature_flags.json → redeploy
• Circuit breaker resets automatically after 60 seconds of no new failures
• When Claude recovers: re-enable flag → redeploy

Stuck pending records

Identifications stuck in pending > 10 minutes indicate a lost BackgroundTask (worker killed).

SELECT id FROM identifications WHERE status='pending' AND identified_at IS NULL;
UPDATE identifications SET status='failed', error_message='Worker lost — please retry' WHERE ...;

Runbook: Rate Limit Issues

Severity: 3 — minor (some users blocked; pro users unaffected)

Detection

• Users report 429 errors
• Check Railway logs for 429 responses

Diagnosis

• Rate limit key format: rate:{user_id}:{YYYY-MM} in Redis
• Check count: redis-cli GET rate:<user_id>:<month>
• Free tier limit: 10 identifications/month (RATE_LIMIT_FREE_TIER env var)

Recovery

• Erroneous block: redis-cli DEL rate:<user_id>:<month> to reset
• Legitimate block: advise user to upgrade to Pro via PATCH /api/v1/user/plan
• If Redis is unreachable: check Railway Redis service health

Budget Alerts (finops-budget-guardrails: alert thresholds at 50%, 80%, 100% of $500 ceiling)

• Railway dashboard → Settings → Usage → Add spend alerts at $250, $400, $500/month
• Supabase dashboard → Settings → Billing → Configure spend alerts
• Cloudflare R2 → Billing → Usage alerts

Cost Targets

All services use free tiers where possible (Supabase free, Railway free, Auth0 free up to 7,500 MAU, Vercel hobby).

Known Gaps and Accepted Trade-offs