SceneScan

SceneScan is an open-source student project for finding Busan filming locations from a reference image or a text query. Production reads are restricted to Busan and use a licensed, provenance-tracked catalog; mock mode remains available for key-free development. UI text is Korean.

Architecture

One Next.js App Router app serves pages and a search API. In real mode, browser Transformers.js produces a 512-dimensional CLIP embedding in a Web Worker; Supabase pgvector ranks location images; server code groups the strongest image per location and returns up to eight locations. Location image embeddings are prepared offline. See architecture, contracts, search ranking, and database.

Business code is grouped into the search and locations domains. External clients live in src/infrastructure, cross-domain errors/logging/UI primitives in src/shared, and shared contracts in src/types.

Local development

Use Node.js 22 and pnpm 10. Copy .env.example to .env.local, or leave it absent to use the default mock mode.

pnpm install
pnpm dev

Open http://localhost:3000, choose 이미지 업로드, select an image, and run a mock search. No account, model download, map key, or Supabase project is needed for public browsing in mock mode. Login/signup stays visible but reports that Auth is not configured until the public Supabase URL and browser-safe key are supplied.

Real browser AI mode accepts JPEG, PNG, and WebP images up to 15 MB, 8192 px per axis, and 20 megapixels. Its first search downloads the public CLIP model; later requests reuse the same worker and model instance. Production uses the WASM backend for broad browser compatibility and keeps only 20 image-free timing samples for diagnostics. Current browser results and the remaining cold-load/WebGPU matrix are in AI performance.

Location detail includes an explicit weather lookup for the current instant or the selected Korea-local shooting date/time. It requires the dedicated server-only KMA_VILLAGE_FORECAST_SERVICE_KEY and service approval; missing credentials produce a retryable unavailable state, not synthetic weather. See the weather contract for forecast limits and attribution.

Environment variables

Variable	Purpose
NEXT_PUBLIC_USE_MOCK_DATA	Defaults to true; false switches server reads/search to Supabase
NEXT_PUBLIC_USE_MOCK_AI	Defaults to true; false loads browser CLIP worker
NEXT_PUBLIC_CLIP_DEVICE	Optional wasm (default) or experimental webgpu; failed WebGPU initialization falls back to WASM
NEXT_PUBLIC_SUPABASE_URL	Supabase project URL for real data
NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY	Preferred browser-safe Supabase key; RLS still defines access
NEXT_PUBLIC_SUPABASE_ANON_KEY	Legacy public anon-key fallback during migration
NEXT_PUBLIC_KAKAO_MAP_KEY	Kakao JavaScript key and registered domain for real map
SUPABASE_URL	Server-only project URL used by the local embedding and locations/parking importers
SUPABASE_SECRET_KEY	Server-only secret key used only for controlled local imports

Never commit .env.local or a Supabase secret/service-role key. Public NEXT_PUBLIC_* variables are visible in the browser bundle. Browser/request-scoped Auth uses only the project URL and publishable (or legacy anon) key; controlled imports keep the admin client and server secret in a separate server-only boundary. Both importers reject either privileged key placed in a NEXT_PUBLIC_* variable. The legacy SUPABASE_SERVICE_ROLE_KEY name remains accepted for existing local setups. Key-free mock browsing remains the default.

Scripts

pnpm dev
pnpm lint
pnpm typecheck
pnpm test
pnpm test:e2e
pnpm test:e2e:auth
pnpm test:e2e:production
pnpm test:integration
pnpm build
pnpm docker:build
pnpm docker:up
pnpm data:normalize data-work/raw/provider.json data-work/mappings/provider.json data-work/normalized/provider.json
pnpm data:import data-work/normalized/provider.json data-work/reports/import.json --validate-only
pnpm data:discover-wikidata data-work/wikidata/commons-manifest.json --base data/production/commons-manifest.json --max 400
pnpm data:collect-commons data/production/commons-manifest.json
pnpm data:upload-storage data/production/locations.json data/production/embeddings-manifest.json data/production --dry-run
pnpm embeddings:prepare scripts/embeddings/manifest.example.json output.json --batch-size 8 --retries 1
pnpm embeddings:import output.json --validate-only
pnpm embeddings:audit-schema
pnpm embeddings:evaluate
pnpm embeddings:evaluate-clip

pnpm test needs no Supabase project or environment variables and is what CI runs on every PR. pnpm test:e2e starts a key-free mock app and exercises the public/browser boundary with the committed project-owned evaluation image; run pnpm exec playwright install chromium once on a new machine. CI runs the same E2E suite against the standalone production image on an isolated Docker network. pnpm test:e2e:auth is an explicit local integration check: start local Supabase first, then it uses Mailpit and the loopback-only Admin key to prove signup → email confirmation → recovery → changed-password login → verified self-deletion, including old-password and stale-cookie rejection. pnpm test:e2e:production is intentionally excluded from PR CI: the separate weekly/manual workflow makes one real CLIP query against PRODUCTION_BASE_URL (default https://beceleb.org) and checks API health plus Kakao markers. pnpm test:integration needs a live Supabase instance (pnpm supabase:start runs one locally via the Supabase CLI) and skips cleanly without one; see testing, Auth email setup, Account deletion, and integration testing for setup.

data:import upserts the locations and parking rows described by a normalized file (no public write API exists for this -- it is the only way real location data enters the database); it does not touch location_images or embeddings. Run it before the embeddings importer, since location_images.location_id is a foreign key to locations.id. See data pipeline for upsert keys, dry-run/apply modes, and the image storage strategy.

The preparation command is for licensed local images after replacing the example manifest paths, UUIDs, and provenance fields. It validates image bytes and metadata, processes configurable batches, writes an atomic resumable JSON checkpoint after every batch, and retries prior failures on the next run. Import defaults to credential-free validation; database dry-run and apply modes are documented in offline embeddings.

The committed source catalog still includes historical nationwide records; the application does not serve them outside Busan. As of 2026-10-11, data/production/locations.json contains 223 source locations, including 36 Busan locations (34 with reviewed districts). A committed catalog entry is not proof it has been imported: verify the hosted database and image/vector coverage separately before claiming production availability. Runtime image URLs use Supabase Storage; wikidata-*.jpg working files are regenerated by the Commons collector rather than committed. See search and data feasibility and maintenance log for coverage and rollout limitations.

The evaluation command compares max and top-k mean ranking at several thresholds on the committed synthetic policy scenarios. embeddings:evaluate-clip regenerates measured cosine scores from the MIT-licensed synthetic image regression set with the production CLIP model; see retrieval evaluation.

Team and deployment

Four path owners are defined in team ownership and AGENTS.md. Contribution steps are in CONTRIBUTING.md. Production runs at beceleb.org on Vercel Hobby with Cloudflare DNS; Supabase Free backs real data when enabled. The same standalone app can be built and smoke-tested with Docker. See deployment.

배포 담당자는 migration, 환경변수, SMTP/callback, 데이터 적재, smoke, rollback을 release checklist 순서로 확인해야 합니다. CI 성공만으로 실제 Production 배포 성공을 의미하지 않습니다.

License

Code is MIT licensed. Fixture images are project-created synthetic illustrations. Third-party data and image rights are tracked separately in DATA_LICENSES.md.