# jfeelgoodofficial/minicuration architecture

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

- Interactive diagram: https://gitdiagram.com/jfeelgoodofficial/minicuration
- Repository: https://github.com/jfeelgoodofficial/minicuration

## Overview

1. **Project type**
   - This is a **static marketing/catalog site** for limited-edition trading card art prints.
   - There is **no application backend or database**; the live site is composed of prebuilt HTML pages, images, and SEO files.

2. **Primary user-facing surfaces**
   - `index.html` is the main landing page.
   - `shop.html` is the product listing/catalog view.
   - `about.html` provides brand or artist context.
   - `artists/jfeelgood.html` is an artist-focused page.
   - Individual product pages live under `shop/*.html` for each print.

3. **Content organization**
   - The repository is structured around **static pages per product** rather than dynamic rendering.
   - Each print has its own dedicated HTML page, which makes the catalog easy to index and straightforward to share.
   - This design also supports SEO-friendly, crawlable detail pages.

4. **Media and visual assets**
   - Images are stored in `image/`, with a dedicated `image/spin/` area for the 3D card-flip/preview visuals described in the README.
   - The site appears image-heavy, so the asset pipeline is a first-class part of the architecture.
   - The README’s “hover to flip” behavior implies the front end uses visual states and image assets to simulate the card front/back interaction.

5. **Client-side interaction model**
   - The core UX features are:
     - card flip on hover/click,
     - filter controls for availability,
     - modal detail views,
     - responsive mobile layout.
   - These are all delivered on the client side, likely via JavaScript embedded in or associated with the HTML pages, with no server round trips for interaction.

6. **SEO and indexing layer**
   - `robots.txt`, `sitemap.xml`, and `_redirects` show that search visibility and clean routing are intentional parts of the architecture.
   - `llms.txt` suggests additional machine-readable site guidance for LLM-oriented crawlers or tooling.
   - `tests/seo.check.ts` and `scripts/check-seo-files.js` reinforce that SEO files are treated as build-critical artifacts.

7. **Asset maintenance pipeline**
   - The `scripts/` directory is a maintenance toolchain for image and HTML hygiene:
     - image optimization,
     - conversion to WebP,
     - updating image references in HTML,
     - fixing image attributes and spacing,
     - verifying generated output.
   - This indicates a workflow where static content is edited, then normalized/optimized before deployment.

8. **Quality and validation boundaries**
   - The repo includes multiple validation layers:
     - ESLint for JavaScript/TypeScript,
     - Prettier for formatting,
     - Stylelint for CSS,
     - HTML validation via `htmlvalidate`,
     - Playwright for browser-level checks,
     - Lighthouse configuration for performance/SEO audits.
   - This is a static-site architecture with strong content QA rather than runtime observability.

9. **End-to-end test coverage**
   - `tests/home.e2e.ts`, `tests/shop.e2e.ts`, `tests/product.e2e.ts`, and `tests/seo.check.ts` cover the critical user flows:
     - landing page,
     - catalog page,
     - product detail pages,
     - SEO integrity.
   - The test suite reflects the main architectural boundaries: home, browse, detail, and discoverability.

10. **Deployment model**
   - The presence of `_redirects`, static HTML pages, and GitHub workflow files strongly suggests deployment as a **static site**, likely via GitHub Pages or a similar static host.
   - There is no evidence of server-side rendering or API dependencies in the runtime path.

11. **Technology profile**
   - Tooling is centered on **Node-based maintenance and testing** (`package.json`, Playwright, Lighthouse, CI workflow) with at least one Python verification/cleanup script.
   - The runtime experience for visitors remains purely static; the build/test toolchain is what adds structure and quality.

12. **Architecture summary for a diagram**
   - A good diagram would show:
     - **source content/pages** at the center,
     - **image pipeline scripts** feeding optimized assets into the site,
     - **validation/test tooling** wrapping the site,
     - **static hosting/redirects/SEO files** as the delivery layer,
     - and **no backend services** in the request path.

Main entry points: [`.github/workflows/ci.yml`](https://github.com/jfeelgoodofficial/minicuration/blob/main/.github/workflows/ci.yml) (CI), [`index.html`](https://github.com/jfeelgoodofficial/minicuration/blob/main/index.html) (Home), [`shop.html`](https://github.com/jfeelgoodofficial/minicuration/blob/main/shop.html) (Catalog), [`shop/a-simple-meditation.html`](https://github.com/jfeelgoodofficial/minicuration/blob/main/shop/a-simple-meditation.html) (Print pages)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_public["Public site"]
  node_index["Home<br/>landing page<br/>[index.html]"]
  node_shop_listing["Catalog<br/>shop page<br/>[shop.html]"]
  node_about_page["About<br/>brand page<br/>[about.html]"]
  node_artist_page["Artist page<br/>artist profile<br/>[jfeelgood.html]"]
  node_product_pages["Print pages<br/>static detail set"]
end

subgraph group_assets["Media assets"]
  node_image_root["Images<br/>media library"]
  node_spin_media["Spin views<br/>preview assets"]
end

subgraph group_delivery["SEO & delivery"]
  node_robots["Robots<br/>crawler policy<br/>[robots.txt]"]
  node_sitemap["Sitemap<br/>index map<br/>[sitemap.xml]"]
  node_redirects["Redirects<br/>routing rules"]
  node_llms["LLM guide<br/>machine hints<br/>[llms.txt]"]
end

subgraph group_qa["Tooling & QA"]
  node_ci_workflow["CI<br/>workflow<br/>[ci.yml]"]
  node_seo_check["SEO check<br/>test<br/>[seo.check.ts]"]
  node_home_test["Home test<br/>e2e test<br/>[home.e2e.ts]"]
  node_shop_test["Catalog test<br/>e2e test<br/>[shop.e2e.ts]"]
  node_product_test["Product test<br/>e2e test<br/>[product.e2e.ts]"]
  node_image_scripts["Image tools<br/>maintenance scripts<br/>[optimize-images.js]"]
  node_html_scripts["HTML tools<br/>maintenance scripts"]
end

node_index -->|"browse"| node_shop_listing
node_index -->|"about"| node_about_page
node_index -->|"artist"| node_artist_page
node_shop_listing -->|"open item"| node_product_pages
node_product_pages -->|"show art"| node_image_root
node_product_pages -->|"flip view"| node_spin_media
node_shop_listing -->|"thumbnails"| node_image_root
node_artist_page -->|"artwork"| node_image_root
node_robots -->|"discover"| node_sitemap
node_sitemap -->|"includes"| node_index
node_sitemap -->|"includes"| node_shop_listing
node_sitemap -->|"includes"| node_product_pages
node_redirects -->|"route"| node_index
node_llms -->|"guide"| node_index
node_image_scripts -->|"optimize"| node_image_root
node_html_scripts -->|"rewrite"| node_product_pages
node_html_scripts -->|"rewrite"| node_shop_listing
node_ci_workflow -->|"run"| node_seo_check
node_ci_workflow -->|"run"| node_home_test
node_ci_workflow -->|"run"| node_shop_test
node_ci_workflow -->|"run"| node_product_test
node_ci_workflow -->|"verify"| node_image_scripts
node_ci_workflow -->|"verify"| node_html_scripts

click node_index "https://github.com/jfeelgoodofficial/minicuration/blob/main/index.html"
click node_shop_listing "https://github.com/jfeelgoodofficial/minicuration/blob/main/shop.html"
click node_about_page "https://github.com/jfeelgoodofficial/minicuration/blob/main/about.html"
click node_artist_page "https://github.com/jfeelgoodofficial/minicuration/blob/main/artists/jfeelgood.html"
click node_product_pages "https://github.com/jfeelgoodofficial/minicuration/blob/main/shop/a-simple-meditation.html"
click node_image_root "https://github.com/jfeelgoodofficial/minicuration/tree/main/image"
click node_spin_media "https://github.com/jfeelgoodofficial/minicuration/tree/main/image/spin"
click node_robots "https://github.com/jfeelgoodofficial/minicuration/blob/main/robots.txt"
click node_sitemap "https://github.com/jfeelgoodofficial/minicuration/blob/main/sitemap.xml"
click node_redirects "https://github.com/jfeelgoodofficial/minicuration/tree/main/_redirects"
click node_llms "https://github.com/jfeelgoodofficial/minicuration/blob/main/llms.txt"
click node_ci_workflow "https://github.com/jfeelgoodofficial/minicuration/blob/main/.github/workflows/ci.yml"
click node_seo_check "https://github.com/jfeelgoodofficial/minicuration/blob/main/tests/seo.check.ts"
click node_home_test "https://github.com/jfeelgoodofficial/minicuration/blob/main/tests/home.e2e.ts"
click node_shop_test "https://github.com/jfeelgoodofficial/minicuration/blob/main/tests/shop.e2e.ts"
click node_product_test "https://github.com/jfeelgoodofficial/minicuration/blob/main/tests/product.e2e.ts"
click node_image_scripts "https://github.com/jfeelgoodofficial/minicuration/blob/main/scripts/optimize-images.js"
click node_html_scripts "https://github.com/jfeelgoodofficial/minicuration/blob/main/scripts/update-html-images.js"

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_index,node_shop_listing,node_about_page,node_artist_page,node_product_pages toneBlue
class node_image_root,node_spin_media toneAmber
class node_robots,node_sitemap,node_redirects,node_llms toneMint
class node_ci_workflow,node_seo_check,node_home_test,node_shop_test,node_product_test,node_image_scripts,node_html_scripts toneRose
```

## Components

### Public site

Static marketing and catalog pages

- [Home](https://github.com/jfeelgoodofficial/minicuration/blob/main/index.html): landing page · Main entry point for the site · `index.html`
- [Catalog](https://github.com/jfeelgoodofficial/minicuration/blob/main/shop.html): shop page · Browseable product listing · `shop.html`
- [About](https://github.com/jfeelgoodofficial/minicuration/blob/main/about.html): brand page · Brand and artist context · `about.html`
- [Artist page](https://github.com/jfeelgoodofficial/minicuration/blob/main/artists/jfeelgood.html): artist profile · Artist-specific feature page · `artists/jfeelgood.html`
- [Print pages](https://github.com/jfeelgoodofficial/minicuration/blob/main/shop/a-simple-meditation.html): static detail set · SEO-friendly per-print product pages · `shop/a-simple-meditation.html`

### Media assets

Product images and preview visuals

- [Images](https://github.com/jfeelgoodofficial/minicuration/tree/main/image): media library · Primary site imagery and product art · `image`
- [Spin views](https://github.com/jfeelgoodofficial/minicuration/tree/main/image/spin): preview assets · 3D flip and hover preview imagery · `image/spin`

### SEO & delivery

Search and hosting-oriented files

- [Robots](https://github.com/jfeelgoodofficial/minicuration/blob/main/robots.txt): crawler policy · Search engine crawl guidance · `robots.txt`
- [Sitemap](https://github.com/jfeelgoodofficial/minicuration/blob/main/sitemap.xml): index map · URL inventory for discovery · `sitemap.xml`
- [Redirects](https://github.com/jfeelgoodofficial/minicuration/tree/main/_redirects): routing rules · Static host routing and aliases · `_redirects`
- [LLM guide](https://github.com/jfeelgoodofficial/minicuration/blob/main/llms.txt): machine hints · Crawler guidance for LLM tools · `llms.txt`

### Tooling & QA

Maintenance scripts and validation

- [CI](https://github.com/jfeelgoodofficial/minicuration/blob/main/.github/workflows/ci.yml): workflow · Automated validation and checks · `.github/workflows/ci.yml`
- [SEO check](https://github.com/jfeelgoodofficial/minicuration/blob/main/tests/seo.check.ts): test · Validates crawlable site artifacts · `tests/seo.check.ts`
- [Home test](https://github.com/jfeelgoodofficial/minicuration/blob/main/tests/home.e2e.ts): e2e test · Checks the landing page flow · `tests/home.e2e.ts`
- [Catalog test](https://github.com/jfeelgoodofficial/minicuration/blob/main/tests/shop.e2e.ts): e2e test · Checks the catalog browsing flow · `tests/shop.e2e.ts`
- [Product test](https://github.com/jfeelgoodofficial/minicuration/blob/main/tests/product.e2e.ts): e2e test · Checks individual product detail pages · `tests/product.e2e.ts`
- [Image tools](https://github.com/jfeelgoodofficial/minicuration/blob/main/scripts/optimize-images.js): maintenance scripts · Optimize, convert, and normalize images · `scripts/optimize-images.js`
- [HTML tools](https://github.com/jfeelgoodofficial/minicuration/blob/main/scripts/update-html-images.js): maintenance scripts · Update image references and page formatting · `scripts/update-html-images.js`

## Connections

- Home → Catalog: browse · Landing page routes into the catalog
- Home → About: about · Landing page links to brand context
- Home → Artist page: artist · Landing page can surface artist context
- Catalog → Print pages: open item · Catalog links to per-print pages
- Print pages → Images: show art · Detail pages render product imagery
- Print pages → Spin views: flip view · Interactive previews use spin assets
- Catalog → Images: thumbnails · Catalog uses image assets for product cards
- Artist page → Images: artwork · Artist page uses site imagery
- Robots → Sitemap: discover · Crawl files work together for indexing
- Sitemap → Home: includes · Sitemap enumerates the main public pages
- Sitemap → Catalog: includes · Sitemap enumerates the catalog
- Sitemap → Print pages: includes · Sitemap enumerates product detail pages
- Redirects → Home: route · Static host rules direct traffic to the site
- LLM guide → Home: guide · Machine-readable site guidance references the public surface
- Image tools → Images: optimize · Maintenance scripts normalize and compress media
- HTML tools → Print pages: rewrite · Scripts update image references in product HTML
- HTML tools → Catalog: rewrite · Scripts maintain catalog page image markup
- CI → SEO check: run · CI runs SEO integrity checks
- CI → Home test: run · CI runs landing page checks
- CI → Catalog test: run · CI runs catalog checks
- CI → Product test: run · CI runs product page checks
- CI → Image tools: verify · CI validates the asset maintenance toolchain
- CI → HTML tools: verify · CI validates HTML/image hygiene tools