photos.kennethreitz.org/CLAUDE.md

CLAUDE.md

Project

photos.kennethreitz.org (codename: ExifTree) — a personal photography portfolio organized by gear, places, and subjects. AI-powered metadata, EXIF-based discovery, infinite scroll.

Live: https://photos.kennethreitz.org Repo: github.com/kennethreitz/photos.kennethreitz.org Stack: Django 6.x · Python 3.14 · PostgreSQL · Celery · django-bolt · Tigris (S3) · OpenAI Deploy: Fly.io with GitHub Actions auto-deploy on push to main

Architecture

Single-tenant. One owner account. No public registration, no multi-user features.

Apps

• core — All models (User, Image, ExifData, Camera, Lens, Tag, City, SiteConfig). Other apps import from here but never the reverse.
• tree — Browse pages: cameras, lenses, tags, cities. No models, reads from core.
• gallery — Collections for organizing photos into curated sets.
• ingest — Upload pipeline, EXIF extraction, thumbnail generation, AI description, geocoding.
• search — Full-text search across titles, descriptions, AI fields, and tags.

Image Pipeline (ingest)

1. Validate format/size
2. Extract EXIF
3. Normalize camera/lens (deduplicate manufacturer strings)
4. Compute perceptual hash (visual dedup)
5. Generate thumbnails (small 300px, medium 800px, large 1600px)
6. Create ExifData record
7. Reverse geocode GPS to city (offline, blocks invalid countries)
8. Apply cleanup rules (delete/fix based on date, country)
9. Mark processed
10. Dispatch AI description task (async via Celery)

Cleanup Rules

Defined in core/management/commands/cleanup.py and enforced inline in ingest/pipeline.py:

Delete: years 2008, 2019, 2020. Dates: Dec 26 2014, Dec 22 2017. Fix: clear date_taken for years before 2008 and 2021+ (incorrect EXIF dates). Cities: block CN, JP, KG, MN, RU entirely. India allows only Bangalore/Mysore.

Invalid countries are blocked at four levels: City.from_coordinates(), ingest/pipeline.py, geocode command, and cleanup command.

AI Metadata

GPT-4o-mini with structured output generates per-image:

• Title — short, evocative (3-7 words)
• Description — 2-3 sentences
• Tags — 5-10 single-word lowercase tags

Configured via SiteConfig admin (OpenAI key + custom prompt).

Code Style

• Python: PEP 8, type hints on function signatures
• Django: fat models, thin views — logic lives on the model or in service functions
• Imports: stdlib → third-party → django → local apps, separated by blank lines
• Strings: double quotes for user-facing, single quotes for identifiers
• Templates: HTMX for interactivity, vanilla JS only where required (upload drag-drop, manage multi-select)
• Tests: use pytest + pytest-django

Models

• UUIDField primary keys everywhere (not auto-increment)
• created_at/updated_at timestamps on every model
• SlugField on anything in a URL
• ExifData stores raw EXIF as JSONField — never throw away the raw data
• Camera/Lens are canonical: raw EXIF strings normalized via core/normalization.py

Frontend

Django templates + HTMX. No frontend framework. Session auth. Minimal vanilla JS.

• Infinite scroll via HTMX hx-trigger="revealed" with stable shuffle per session
• CSS cache-busting via content hash in context processor
• Analytics snippet configurable in SiteConfig admin

URLs

• / — home with infinite scroll, year filter
• /cameras/, /cameras/<slug>/ — gear browsing
• /lenses/, /lenses/<slug>/
• /tags/, /tags/<slug>/ — AI-generated tag cloud
• /cities/, /cities/<slug>/ — GPS-based location browsing
• /collections/, /collections/<slug>/
• /images/<uuid>/ — detail with EXIF bar, prev/next, keyboard nav
• /manage/ — photo manager with multi-select, bulk actions, faceted filters
• /upload/ — drag-drop upload with progress
• /dashboard/ — owner dashboard
• /search/ — full-text search with EXIF filters
• /admin/ — Django admin (SiteConfig, models)

Infrastructure

• Fly.io: single web process (django-bolt). The worker process group is currently absent in fly.toml — Celery tasks (AI metadata, etc.) have no consumer in production. Re-add when needed.
• PostgreSQL: Fly Postgres on exiftree-db, single shared-cpu-1x:2048MB machine (bumped from 1GB after an OOM in mid-April 2026). Also Celery broker via sqla+postgresql://.
• Tigris: S3-compatible object storage for all images (used locally and in prod). CORS is configured on the exiftree-media bucket for photos.kennethreitz.org + localhost:8000 + 127.0.0.1:8000.
• Redis: local-only Celery broker (brew service). Not used in production.
• GitHub Actions:
  • deploy.yml — auto-deploy on push to main via flyctl deploy --remote-only
  • daily-restart.yml — fly apps restart exiftree at 08:00 UTC. Originally added as a band-aid for an app wedge that surfaced after Postgres restarts; v118 (April 19 2026) appears to have fixed the wedge but the daily restart is still in place as a safety net.
• python-dotenv: .env loaded automatically in manage.py

Management Commands

import_folder /path   # Bulk import with auto-seek, dedup, concurrent workers
import_flickr <user>  # Import from Flickr via API
ai_describe           # Backfill AI metadata (--tail for continuous watch)
geocode               # Batch reverse geocode GPS to cities
cleanup               # Run all cleanup rules
dedupe                # Remove visual duplicates via perceptual hash
reprocess             # Re-process stuck images

When Working on This

• Don't add dependencies without discussing tradeoffs
• Prefer Django builtins over third-party packages
• Write reversible migrations
• Keep core minimal — if logic could live in core or a feature app, default to the feature app
• Cleanup rules must be mirrored in both the cleanup command and pipeline.py
• Restart Celery workers after code changes (they cache old Python modules)
• conn_max_age=60 and CELERY_BROKER_POOL_LIMIT=1 to prevent DB connection exhaustion