Developer Overview & System Guide | Developer & Build Documentation

System Purpose & Objectives

This web application represents the production ecommerce storefront for Rory Skagen Art, engineered on Next.js 15 App Router and integrated with Fourthwall's headless commerce APIs.

The project fulfills two primary operational mandates:

1. High-Performance Omnichannel Storefront: Fast, beautifully rendered fine art catalog supporting responsive layouts, multi-currency switching (USD, EUR, GBP, CAD, AUD), and persistent cart management.

2. Catalog Migration & Sync Engine: Automated ingestion and synchronization pipeline that extracted 137 fine art masterworks from the legacy Supabase/Vercel codebase (jadenblack/roryskagenart.com) and mapped them into Fourthwall's Platform and Storefront data layers.

Core Technology Stack

Framework: Next.js 15.6 (App Router with Turbopack & ISR)
Runtime: Node.js 22 LTS
UI & Styling: Tailwind CSS 3.4 with container queries, clsx, and lucide-react
E-Commerce Layer: Fourthwall Storefront API (v1) & Fourthwall Platform Open API (v1.0)
Content & Documentation: Fumadocs Core 16.x & Fumadocs UI
Media Hosting: Cloudinary CDN & Supabase Storage (public WebP renditions)
Quality & Testing: TypeScript 5.5, Vitest 4.0, ESLint

Key Features & Capabilities

137 Cataloged Artworks: 100% of Rory Skagen's fine art catalog imported with verified high-resolution images, descriptions, dimensions, mediums, and tags.
Dynamic Collection Routing: Dedicated routes for all signature series (austin-iconic, monsters-kaiju, pop-surrealism, atomic-sci-fi, launch, all).
Interactive Importer UI (/import): Visual web dashboard for catalog inspection, connection testing, CSV export, and live API synchronization.
Fumadocs Documentation (/docs & /docs/dev): Dual-purpose documentation engine serving customer-facing guides and developer runbooks.

Repository File Map

/
├── app/
│   ├── [currency]/            # Dynamic currency-scoped storefront routes
│   │   ├── page.tsx           # Home page with hero, 3-item grid & carousel
│   │   ├── collections/       # Collection filtering routes
│   │   ├── product/           # Product detail page (PDP)
│   │   └── search/            # Search & sort page
│   ├── api/
│   │   └── import/fourthwall/ # Importer REST API (GET status, POST sync, CSV)
│   ├── docs/                  # Fumadocs public documentation routes
│   │   ├── page.tsx
│   │   └── dev/               # Fumadocs developer & build documentation
│   ├── import/                # Interactive admin sync dashboard
│   ├── layout.tsx             # Root application layout
│   └── globals.css            # Tailwind & Fumadocs global styles
├── components/
│   ├── cart/                  # Cart modal, server actions, cookie storage
│   ├── docs/                  # Fumadocs navigation, sidebar & layout
│   ├── grid/                  # 3-item grid, tile components
│   └── layout/                # Storefront Navbar, Footer, Currency selector
├── lib/
│   ├── fourthwall/
│   │   ├── index.ts           # Storefront data layer, mock fallback, cart API
│   │   ├── importer.ts        # Sync engine, CSV generator, API client
│   │   ├── reshape.ts         # Normalizes Fourthwall DTOs into standard types
│   │   ├── types.ts           # TypeScript interfaces for Fourthwall schemas
│   │   └── rory-artworks-data.json # 137 fine art pieces canonical snapshot
│   ├── docs-content.ts        # Fumadocs documentation data source
│   ├── constants.ts           # Store constants & cache tags
│   └── utils.ts               # Environment variable sanitization & helpers
└── scripts/
    └── import-artworks-to-fourthwall.ts # Standalone CLI import tool