How lewdry/artflip works
1. Overall shape
- ArtFlip is a static Svelte + Vite front end that serves a browser-based artwork viewer.
- The app itself does not appear to depend on a live application backend; instead it consumes prebuilt JSON data files and local images from the public/ directory.
2. Primary runtime boundary
- The browser runs the Svelte app in src/.
- The build/dev toolchain is Node.js/Vite/Svelte, with index.html as the entry shell and src/main.js bootstrapping src/App.svelte.
3. Main user-facing subsystems
- There are two core UI modes:
- a single-artwork viewer with random launch, next/previous navigation, preloading, history, and deep-linking via URL state;
- a grid view at /?mode=grid that shows many thumbnails and supports open/zoom behavior.
- Shared presentation code is split into reusable Svelte components under src/lib/ such as GridView.svelte and Counter.svelte.
4. Data model and content storage
- Artwork data is stored as static assets under public/metadata/{id}.json.
- A global list of candidate IDs lives in public/artworkids.json.
- Each artwork metadata file is expected to include at least a localImage path, which makes the frontend image loading local and deterministic.
5. Image and thumbnail pipeline
- The repo includes public/images/ and public/thumbs/, indicating separate storage for full-size artwork images and thumbnail assets.
- Thumbnails are likely precomputed rather than generated at runtime, keeping the browser app lightweight.
6. Metadata/content generation scripts
- The scripts/ directory contains automation for maintaining the dataset:
- museum-specific fetchers such as autometfetch.py, autochicfetch.py, autoclevefetch.py, automiafetch.py, autorijksfetch.py;
- generate_thumbs.js for thumbnail creation;
- utilities like delete_artwork.py, count_by_museum.py, and deploycheck.py.
- This creates a clear separation between content ingestion/build-time processing and the browser runtime.
7. Museum-specific ingestion boundary
- The dataset is assembled from multiple collections: Metropolitan Museum of Art, Art Institute of Chicago, Rijksmuseum, Cleveland Museum of Art, Minneapolis Institute of Art, and others referenced in the README counts.
- The *dontfetch.json files act as exclusion lists, so the ingestion pipeline can omit problematic or undesired records without changing frontend code.
8. Automation and CI/CD
- GitHub Actions workflows in .github/workflows/ mirror the content pipeline:
- museum fetch jobs,
- an autobot job,
- and a deploy.yml.
- This suggests the repo is maintained via scheduled or triggered updates that regenerate data and then publish the static site.
9. Deployment model
- Because the app is static, deployment is likely the final step of publishing the built frontend plus the public/ asset set.
- The architecture boundary is therefore: automation updates the dataset → Vite builds the Svelte app → static deployment serves assets to browsers.
10. Navigation and state flow in the browser
- On launch, the app selects a random artwork ID from the dataset.
- Navigation events update the current artwork, maintain a bounded history, and sync the selection into the URL for shareable deep links.
- Upcoming artwork images are preloaded to make edge-click, keyboard, and swipe navigation feel instantaneous.
11. External dependencies and trust boundary
- The content comes from public-domain museum collections and is treated as static reference data, not user-generated or mutable app state.
- The frontend’s only meaningful external dependency is the hosted static asset origin serving JSON metadata and images; the museums are upstream data sources used by the scripts, not by the browser app directly.
12. What to diagram
- Draw three major layers:
- Content sources + fetch scripts on the left,
- Static generated assets in public/ in the middle,
- Svelte browser app on the right.
- Show the browser reading artworkids.json, per-artwork metadata, thumbnails, and local images; show CI/CD as the mechanism that refreshes and deploys the static bundle and content.
Main entry points: autometfetch.py Fetchers · App.svelte App shell · deploycheck.py Maintenance · 100050.json Metadata
Components 18
Content pipeline
Museum ingestion, exclusions, and static artwork assets.
- Museums · Upstream museum collections used to assemble the artwork dataset.
- Fetchers · Museum-specific scripts that retrieve and normalize artwork records.
scripts/autometfetch.py - Exclusions · Per-museum dontfetch lists that filter out unwanted records during ingestion.
scripts/metdontfetch.json - Thumb build · Generates thumbnail assets for the static artwork library.
scripts/generate_thumbs.js - Metadata · Per-artwork metadata files keyed by artwork ID.
public/metadata/100050.json - Artwork IDs · Global list of candidate artwork IDs for random selection and browsing.
public/artworkids.json - Images · Full-size local artwork image assets served to the browser.
public/images - Thumbnails · Precomputed thumbnail assets used by the grid view.
public/thumbs
Browser app
Svelte/Vite frontend that reads generated content and renders viewer modes.
- Entry shell · Document entry point that loads the frontend bundle.
index.html - Bootstrap · Starts the Svelte application in the browser.
src/main.js - App shell · Top-level application controller and mode switcher.
src/App.svelte - Viewer mode · Single-artwork browsing with random launch, navigation, history, preloading, and URL state.
src/App.svelte - Grid mode · Gallery view for browsing many artworks and opening them quickly.
src/lib/GridView.svelte - Shared UI · Reusable presentation pieces such as counters and grid controls.
src/lib/Counter.svelte - Asset fetch · Browser reads metadata JSON, artwork IDs, thumbnails, and local images from the static origin.
Automation
Scheduled fetch, maintenance, and deployment workflows.
- Fetch workflows · Automation jobs that run museum-specific fetchers on a schedule or trigger.
.github/workflows/metfetch.yml - Deploy workflow · Publishes the built static site and refreshed assets.
.github/workflows/deploy.yml - Maintenance · Dataset hygiene and checks such as artwork deletion, counts, deploy validation, and autobot coordination.
scripts/deploycheck.py
Connections 23
- Museums → Fetchers: upstream data · Museums provide records consumed by the ingestion scripts.
- Fetchers → Exclusions: filters · Fetcher scripts consult dontfetch lists before writing content.
- Fetchers → Metadata: writes · Fetched records are materialized as per-artwork metadata JSON.
- Fetchers → Artwork IDs: updates · Fetcher runs refresh the global artwork ID list.
- Thumb build → Thumbnails: creates · Thumbnail generation produces the static thumb assets.
- Metadata → Asset fetch: served as · The app loads artwork metadata directly from static files.
- Artwork IDs → Asset fetch: read by · The browser uses the ID index to choose and navigate artworks.
- Images → Asset fetch: served as · Full-size images are fetched as local static assets.
- Thumbnails → Asset fetch: served as · The grid view uses thumbnail assets from the static origin.
- Entry shell → Bootstrap: loads · The HTML shell loads the frontend entry script.
- Bootstrap → App shell: mounts · Main bootstrapping code mounts the Svelte app root.
- App shell → Viewer mode: routes · Default mode shows the single-artwork viewer.
- App shell → Grid mode: routes · Grid mode is selected through URL state.
- Viewer mode → Asset fetch: consumes · Viewer loads IDs, metadata, and local artwork images.
- Grid mode → Asset fetch: consumes · Grid view loads thumbnails and related metadata.
- Shared UI → Viewer mode: supports · Reusable UI pieces support the viewer experience.
- Shared UI → Grid mode: supports · Reusable UI pieces support the grid experience.
- Fetch workflows → Fetchers: runs · GitHub Actions invoke the museum fetchers and dataset builders.
- Fetch workflows → Maintenance: orchestrates · Workflows coordinate checks and maintenance utilities.
- Deploy workflow → Asset fetch: publishes · Deployment publishes the static content bundle and assets.
- Deploy workflow → App shell: publishes · Deployment includes the built frontend application.
- Maintenance → Fetchers: maintains · Maintenance scripts help clean and verify the generated dataset.
- Maintenance → Metadata: sanitizes · Maintenance utilities can inspect or delete artwork metadata.