# lewdry/artflip architecture

> Architecture diagram of the GitHub repository lewdry/artflip, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/lewdry/artflip
- Repository: https://github.com/lewdry/artflip

## Overview

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: [`scripts/autometfetch.py`](https://github.com/lewdry/artflip/blob/main/scripts/autometfetch.py) (Fetchers), [`src/App.svelte`](https://github.com/lewdry/artflip/blob/main/src/App.svelte) (App shell), [`scripts/deploycheck.py`](https://github.com/lewdry/artflip/blob/main/scripts/deploycheck.py) (Maintenance), [`public/metadata/100050.json`](https://github.com/lewdry/artflip/blob/main/public/metadata/100050.json) (Metadata)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_content["Content pipeline"]
  node_museum_sources(("Museums<br/>external data sources"))
  node_fetch_scripts["Fetchers<br/>ingestion scripts<br/>[autometfetch.py]"]
  node_exclude_lists["Exclusions<br/>selection lists<br/>[metdontfetch.json]"]
  node_thumb_builder["Thumb build<br/>asset generation<br/>[generate_thumbs.js]"]
  node_metadata_store["Metadata<br/>static JSON<br/>[100050.json]"]
  node_id_index["Artwork IDs<br/>lookup JSON<br/>[artworkids.json]"]
  node_image_store[("Images")]
  node_thumb_store[("Thumbnails")]
end

subgraph group_runtime["Browser app"]
  node_entry_shell["Entry shell<br/>vite html entry<br/>[index.html]"]
  node_bootstrap["Bootstrap<br/>client entry<br/>[main.js]"]
  node_app_shell["App shell<br/>svelte root<br/>[App.svelte]"]
  node_viewer_mode["Viewer mode<br/>artwork viewer<br/>[App.svelte]"]
  node_grid_mode["Grid mode<br/>thumbnail browser<br/>[GridView.svelte]"]
  node_shared_ui["Shared UI<br/>svelte components<br/>[Counter.svelte]"]
  node_browser_assets["Asset fetch<br/>static asset access"]
end

subgraph group_automation["Automation"]
  node_fetch_workflows["Fetch workflows<br/>github actions<br/>[metfetch.yml]"]
  node_deploy_workflow["Deploy workflow<br/>github actions<br/>[deploy.yml]"]
  node_maintenance_tools["Maintenance<br/>scripts<br/>[deploycheck.py]"]
end

node_museum_sources -->|"upstream data"| node_fetch_scripts
node_fetch_scripts -->|"filters"| node_exclude_lists
node_fetch_scripts -->|"writes"| node_metadata_store
node_fetch_scripts -->|"updates"| node_id_index
node_thumb_builder -->|"creates"| node_thumb_store
node_metadata_store -->|"served as"| node_browser_assets
node_id_index -->|"read by"| node_browser_assets
node_image_store -->|"served as"| node_browser_assets
node_thumb_store -->|"served as"| node_browser_assets
node_entry_shell -->|"loads"| node_bootstrap
node_bootstrap -->|"mounts"| node_app_shell
node_app_shell -->|"routes"| node_viewer_mode
node_app_shell -->|"routes"| node_grid_mode
node_viewer_mode -->|"consumes"| node_browser_assets
node_grid_mode -->|"consumes"| node_browser_assets
node_shared_ui -->|"supports"| node_viewer_mode
node_shared_ui -->|"supports"| node_grid_mode
node_fetch_workflows -->|"runs"| node_fetch_scripts
node_fetch_workflows -->|"orchestrates"| node_maintenance_tools
node_deploy_workflow -->|"publishes"| node_browser_assets
node_deploy_workflow -->|"publishes"| node_app_shell
node_maintenance_tools -->|"maintains"| node_fetch_scripts
node_maintenance_tools -->|"sanitizes"| node_metadata_store

click node_fetch_scripts "https://github.com/lewdry/artflip/blob/main/scripts/autometfetch.py"
click node_exclude_lists "https://github.com/lewdry/artflip/blob/main/scripts/metdontfetch.json"
click node_thumb_builder "https://github.com/lewdry/artflip/blob/main/scripts/generate_thumbs.js"
click node_metadata_store "https://github.com/lewdry/artflip/blob/main/public/metadata/100050.json"
click node_id_index "https://github.com/lewdry/artflip/blob/main/public/artworkids.json"
click node_image_store "https://github.com/lewdry/artflip/tree/main/public/images"
click node_thumb_store "https://github.com/lewdry/artflip/tree/main/public/thumbs"
click node_entry_shell "https://github.com/lewdry/artflip/blob/main/index.html"
click node_bootstrap "https://github.com/lewdry/artflip/blob/main/src/main.js"
click node_app_shell "https://github.com/lewdry/artflip/blob/main/src/App.svelte"
click node_viewer_mode "https://github.com/lewdry/artflip/blob/main/src/App.svelte"
click node_grid_mode "https://github.com/lewdry/artflip/blob/main/src/lib/GridView.svelte"
click node_shared_ui "https://github.com/lewdry/artflip/blob/main/src/lib/Counter.svelte"
click node_fetch_workflows "https://github.com/lewdry/artflip/blob/main/.github/workflows/metfetch.yml"
click node_deploy_workflow "https://github.com/lewdry/artflip/blob/main/.github/workflows/deploy.yml"
click node_maintenance_tools "https://github.com/lewdry/artflip/blob/main/scripts/deploycheck.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_museum_sources,node_fetch_scripts,node_exclude_lists,node_thumb_builder,node_metadata_store,node_id_index,node_image_store,node_thumb_store toneBlue
class node_entry_shell,node_bootstrap,node_app_shell,node_viewer_mode,node_grid_mode,node_shared_ui,node_browser_assets toneAmber
class node_fetch_workflows,node_deploy_workflow,node_maintenance_tools toneMint
```

## Components

### Content pipeline

Museum ingestion, exclusions, and static artwork assets.

- **Museums**: external data sources · Upstream museum collections used to assemble the artwork dataset.
- [Fetchers](https://github.com/lewdry/artflip/blob/main/scripts/autometfetch.py): ingestion scripts · Museum-specific scripts that retrieve and normalize artwork records. · `scripts/autometfetch.py`
- [Exclusions](https://github.com/lewdry/artflip/blob/main/scripts/metdontfetch.json): selection lists · Per-museum dontfetch lists that filter out unwanted records during ingestion. · `scripts/metdontfetch.json`
- [Thumb build](https://github.com/lewdry/artflip/blob/main/scripts/generate_thumbs.js): asset generation · Generates thumbnail assets for the static artwork library. · `scripts/generate_thumbs.js`
- [Metadata](https://github.com/lewdry/artflip/blob/main/public/metadata/100050.json): static JSON · Per-artwork metadata files keyed by artwork ID. · `public/metadata/100050.json`
- [Artwork IDs](https://github.com/lewdry/artflip/blob/main/public/artworkids.json): lookup JSON · Global list of candidate artwork IDs for random selection and browsing. · `public/artworkids.json`
- [Images](https://github.com/lewdry/artflip/tree/main/public/images): static images · Full-size local artwork image assets served to the browser. · `public/images`
- [Thumbnails](https://github.com/lewdry/artflip/tree/main/public/thumbs): static 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](https://github.com/lewdry/artflip/blob/main/index.html): vite html entry · Document entry point that loads the frontend bundle. · `index.html`
- [Bootstrap](https://github.com/lewdry/artflip/blob/main/src/main.js): client entry · Starts the Svelte application in the browser. · `src/main.js`
- [App shell](https://github.com/lewdry/artflip/blob/main/src/App.svelte): svelte root · Top-level application controller and mode switcher. · `src/App.svelte`
- [Viewer mode](https://github.com/lewdry/artflip/blob/main/src/App.svelte): artwork viewer · Single-artwork browsing with random launch, navigation, history, preloading, and URL state. · `src/App.svelte`
- [Grid mode](https://github.com/lewdry/artflip/blob/main/src/lib/GridView.svelte): thumbnail browser · Gallery view for browsing many artworks and opening them quickly. · `src/lib/GridView.svelte`
- [Shared UI](https://github.com/lewdry/artflip/blob/main/src/lib/Counter.svelte): svelte components · Reusable presentation pieces such as counters and grid controls. · `src/lib/Counter.svelte`
- **Asset fetch**: static asset access · Browser reads metadata JSON, artwork IDs, thumbnails, and local images from the static origin.

### Automation

Scheduled fetch, maintenance, and deployment workflows.

- [Fetch workflows](https://github.com/lewdry/artflip/blob/main/.github/workflows/metfetch.yml): github actions · Automation jobs that run museum-specific fetchers on a schedule or trigger. · `.github/workflows/metfetch.yml`
- [Deploy workflow](https://github.com/lewdry/artflip/blob/main/.github/workflows/deploy.yml): github actions · Publishes the built static site and refreshed assets. · `.github/workflows/deploy.yml`
- [Maintenance](https://github.com/lewdry/artflip/blob/main/scripts/deploycheck.py): scripts · Dataset hygiene and checks such as artwork deletion, counts, deploy validation, and autobot coordination. · `scripts/deploycheck.py`

## Connections

- 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.
