Image Catalog and ImageKit Hosting for Arthouse

Status: Draft (v0.0.0.1) Codename: arthouse-site Parent: Polish Pass for Arthouse Site · Maintain an Image Heavy Portfolio Site Related: AI Photo to Illustration Transform for Arthouse

1. Why this spec exists

The arthouse-site code repo is public. The client's photography includes work that is sensitive, sometimes NSFW. Holding image bytes in the repo is therefore not an option — even an old commit on main would leak.

ImageKit (already provisioned for the team) becomes the asset host. The repo holds metadata only: a catalog of records describing every image, with the resolver layer assembling URLs at render time. Galleries reference records by slug; if a file gets renamed or moved on ImageKit, only the record's imagekit_path changes — every gallery pointing at it keeps working.

Privacy is a property of the record, not of a directory. A record can describe an NSFW original (for the artist's own catalog completeness and for tracking which images have been transformed by AI Photo to Illustration Transform for Arthouse) while being unreachable from any public route.

2. The three layers

2.1 Image records

Path: src/content/images/<slug>.md

One markdown file per image. Body is optional (long-form caption / story).

---
title: "Kiara · Audrey Hepburn"
slug: studio-kiara-audrey-hepburn      # explicit; matches filename
kind: photograph                        # photograph | artwork | ai-rendered
privacy: public                         # public | gated | private
nsfw: false
imagekit_path: /portfolio/studio/kiara-audrey-hepburn.jpg
aspect_ratio: "2:3"                     # for layout without CLS
alt: "Portrait styled as Audrey Hepburn — black gown, pearl strand, soft studio light"
caption: "Studio session. Paris, October 2025."
palette_hint: gothic                    # dark | bright | gothic | girly
tags:
  - Portraits
  - Studio
  - Styled
series: studio-sessions
shoot_location: Paris
date_taken: 2025-10-15
pricing_tier: standard
source_image: ~                         # for ai-rendered only
ai_model: ~                             # for ai-rendered only
---

For AI-rendered safe outputs, kind: ai-rendered and source_image: points to the slug of the private source record — preserving lineage without exposing the source.

For private NSFW originals (catalog presence only, never rendered):

---
title: "Private · 2025-10-15 frame 007"
slug: private-2025-10-15-frame-007
kind: photograph
privacy: private
nsfw: true
imagekit_path: /private/2025-10-15/frame-007.jpg
alt: "(private)"
date_taken: 2025-10-15
---

2.2 Galleries reference by slug

src/content/galleries/portrait/studio-sessions.md:

---
title: Studio Sessions
description: Portrait photography — styled sessions with creative direction
cover_image: studio-kiara-audrey-hepburn
images:
  - studio-kiara-audrey-hepburn
  - studio-kiara-steampunk
  - studio-kiara-glitterbug
featured: true
sort_order: 1
tags: [Portraits, Studio, Styled]
date_created: 2026-04-21
---

No paths. Rename an ImageKit asset → update the record's imagekit_path → every gallery follows.

2.3 Resolver library + component

src/lib/imagekit.ts — pure functions:

• getImageRecord(slug) — fetches the content collection entry

• imagekitUrl(record, transformations) — builds ${IMAGEKIT_URL_ENDPOINT}${imagekit_path}?tr=w-800,q-80,f-webp

• imageSrcSet(record, widths) — produces a srcset string for responsive <img>

• filterPublic(records) — strips privacy !== "public" (the load-bearing privacy gate)

src/components/basics/CatalogImage.astro — takes a slug prop, resolves the record, renders a responsive <img> with srcset, sized via aspect_ratio to prevent layout shift. If the record's privacy doesn't match the render context, renders nothing (silently in production, with a comment in dev).

3. Privacy rules (the single load-bearing contract)

nsfw is orthogonal — a marker for the CMS UI to warn before showing a thumbnail. It does not change render behavior. A public + nsfw: false AI-rendered output is rendered freely; the private + nsfw: true source it descended from is not.

Build-time enforcement: every component that pulls images must go through filterPublic() (or the future filterForContext(ctx)). Direct reads of getCollection('images') without filtering are an anti-pattern — surface in code review.

4. ImageKit folder convention

ik.imagekit.io/<account>/
  portfolio/
    studio/             # public
    landscape/
    portrait/
  ai-rendered/          # public — outputs from the AI-transform pipeline
  private/              # signed-URL-only, never linked from public site
    2025-10-15/
    2025-11-02/

Records under privacy: private MUST have imagekit_path starting /private/. A build-time invariant check is cheap to add and prevents misclassification.

Signing for the private/ folder is out of scope for Phase 1. We'll implement signed-URL access if/when we build a gated review surface for the artist herself.

5. Sveltia CMS integration

public/admin/config.yml collection update:

• images collection fields swap src (path) for imagekit_path (relative path under ImageKit endpoint)

• Add: kind (select), privacy (select, default public), nsfw (boolean), aspect_ratio (string), palette_hint (select), series (string), source_image (relation widget pointing back at images collection)

• The CMS no longer uploads image bytes to public/images/ — uploads go directly to ImageKit through their dashboard or via a future custom widget. Phase 1: she uploads to ImageKit, copies the path, pastes into the CMS form.

The galleries collection field for images becomes a relation to image-record slugs rather than a free-form file picker.

6. Environment variables

.env.example adds:

IMAGEKIT_URL_ENDPOINT=https://ik.imagekit.io/your-account-id
# Server-side only, for future signed-URL work on the /private/ folder:
# IMAGEKIT_PRIVATE_KEY=...

The endpoint URL is non-secret (it ends up in client-side <img> src attributes anyway). The private key is server-only and Phase 2.

7. Migration of existing content

One gallery exists today: src/content/galleries/portrait/studio-sessions.md. It references three local JPEG paths. Phase 1 deliverable:

1. Create three image records in src/content/images/ for the existing assets (uses placeholder ImageKit paths — client uploads later)

2. Rewrite the gallery's images: list to reference slugs

3. Keep the local public/images/portfolio/*.jpeg files in place during transition (so the dev server still has something to render until the ImageKit account holds the real assets)

4. The CatalogImage component supports a local_src fallback for the transition period — flag emitted in console when the fallback fires

8. What this spec does NOT do

• Signed URLs for /private/ (Phase 2)

• Per-image color extraction (the palette_hint is a manual hint, not derived)

• AI-transform automation (separate exploration)

• Image upload UI (uses ImageKit dashboard for now)

9. References

• Polish Pass for Arthouse Site — parent

• Maintain an Image Heavy Portfolio Site — grandparent (original site spec)

• AI Photo to Illustration Transform for Arthouse — produces the kind: ai-rendered records this catalog tracks