AI Apparel Marketplace Starter

Open-source Next.js starter for launching an AI-powered apparel marketplace with three built-in surfaces:

• Storefront for shoppers
• Seller portal for catalog and fulfillment workflows
• Admin portal for merchandising, approvals, and platform operations

The starter ships with English, Arabic, and Spanish locale support, R2-based media storage, Neon + Drizzle data access, better-auth authentication, and optional AI features for product discovery, reference-photo try-on, and image/video generation.

This repository is intended to be deployable as a neutral apparel marketplace starter. Some legacy internal names still exist in compatibility layers and database storage, and those are documented below so downstream teams can adopt the repo safely without needing to reverse-engineer historical assumptions.

What It Includes

• Multi-role marketplace flows for buyers, sellers, and admins
• Taxonomy-first product catalog with brands, categories, variants, promotions, reviews, and CMS content blocks
• Built-in locale routing for en, ar, and es, including RTL support for Arabic
• Config-driven store identity, sender name, currency, locale enablement, payment badges, and contact details
• Optional AI shopping assistant with memory, product search, cart actions, and multilingual prompts
• Optional virtual try-on and image/video generation pipelines
• R2-backed product, avatar, and generated-media storage

Architecture Snapshot

• src/app/[locale]/(storefront): shopper storefront, account, cart, checkout, search, and product pages
• src/app/[locale]/(supplier): seller workspace for products, profile, and order fulfillment
• src/app/[locale]/(admin): admin workspace for catalog, content, settings, reviews, promotions, customers, AI, and seller operations
• src/actions: server actions grouped by domain (admin, supplier, storefront, ai, customer)
• src/db/schema.ts: marketplace schema for users, sellers, catalog, orders, reviews, content, store settings, AI conversations, and try-on assets
• src/lib: auth, env validation, provider adapters, AI prompt/tool wiring, store configuration, and storage helpers
• messages/*.json: locale messages merged through next-intl with English fallback behavior

Additional docs:

• Architecture Guide
• Deployment Guide
• Public Release Checklist

Required Services

These services are required for a working baseline deployment:

1. Neon Postgres or any Postgres-compatible database reachable by the app
2. Cloudflare R2 for product media, avatars, and generated assets
3. better-auth configuration via app env vars

Minimum required environment variables:

• Database: DATABASE_URL, DEV_DATABASE_URL, PROD_DATABASE_URL
• Auth: BETTER_AUTH_SECRET, BETTER_AUTH_URL, NEXT_PUBLIC_BETTER_AUTH_URL
• Storage: R2_ACCOUNT_ID, R2_ACCESS_KEY_ID, R2_SECRET_ACCESS_KEY, R2_BUCKET_NAME

Optional Services

The app is designed to remain deployable when these integrations are absent:

• Resend for password-reset and transactional mail
• DeepInfra for the AI shopping assistant text and vision models
• OpenAI for routes or tools that still expect an OpenAI key in local workflows
• RunPod for image-edit / try-on generation
• Runware for AI video generation
• Vercel deployment metadata for preview-aware auth origins

Optional environment variables:

• Vercel metadata: VERCEL_URL, VERCEL_BRANCH_URL, VERCEL_ENV, NODE_ENV
• Email: RESEND_API_KEY, RESEND_FROM_EMAIL, RESEND_FROM_NAME
• AI assistant: DEEPINFRA_API_KEY, OPENAI_API_KEY
• Try-on / image generation: RUNPOD_API_KEY, RUNPOD_BASE_URL, RUNPOD_IMAGE_EDIT_MODEL
• Video generation: RUNWARE_API_KEY
• Store presentation: STORE_LOGO_KEY
• Demo / feature gating: NEXT_PUBLIC_NON_PAYMENT_DISABLED
• Marketplace-managed catalog scripts: MARKETPLACE_INTERNAL_SUPPLIER_ID, INTERNAL_SUPPLIER_EMAIL, INTERNAL_SUPPLIER_NAME, INTERNAL_SUPPLIER_COMPANY_NAME_EN, INTERNAL_SUPPLIER_COMPANY_NAME_AR
• Script-only helpers: DEMO_DATABASE_URL, IMPORT_SOURCE_DIR

Use .env.example as the canonical template. Keep it in sync with runtime usage when adding or removing integrations.

Local Setup

1. Install dependencies.

bun install

2. Copy the environment template.

cp .env.example .env.local

3. Fill in the required database, auth, and R2 variables in .env.local.

4. Push the schema to your development database.

bun run db:dev:push

5. Optionally create the marketplace-managed seller account used by admin workflows and import scripts.

bun run db:create-internal-supplier

6. Start the development server.

bun run dev

7. Verify the repo health.

bun check

Local Development Flow

• bun run dev: Next.js development server
• bun run db:dev:push: push schema to the development database
• bun run db:prod:push: push schema to the production database
• bun run db:dev:studio: open Drizzle Studio against development
• bun run db:prod:studio: open Drizzle Studio against production
• bun run db:create-internal-supplier: create the marketplace-managed seller account and print its ID

The middleware enforces locale-aware redirects and protects /admin, /supplier, and /account routes while allowing public API routes and token-based seller onboarding.

Deployment Flow

Vercel path

1. Create production database and R2 bucket.
2. Add the required env vars to Vercel.
3. Deploy the app.
4. Run bun run db:prod:push against the production database.
5. Create the marketplace-managed seller account if you plan to use marketplace-managed catalog operations.
6. Configure store settings in the admin panel.
7. Enable optional providers only after baseline storefront/admin flows are verified.

Self-hosted path

1. Provide the same env surface from .env.example.
2. Run bun install && bun run build.
3. Push the schema to the target database.
4. Start with bun run start behind your preferred reverse proxy.
5. Confirm BETTER_AUTH_URL and NEXT_PUBLIC_BETTER_AUTH_URL match the external origin exactly.

The detailed deployment sequence, validation steps, and failure modes are in docs/deployment.md.

Feature Flags And Optional Behavior

• NEXT_PUBLIC_NON_PAYMENT_DISABLED=true: disables signup and several AI-assisted admin/storefront actions intended for demo or no-payment environments
• No RESEND_API_KEY: email sending is unavailable; password-reset flows that attempt to send mail will fail clearly
• No DEEPINFRA_API_KEY: AI shopping assistant flows should be treated as disabled
• No RUNPOD_API_KEY: virtual try-on and image-edit generation are unavailable
• No RUNWARE_API_KEY: generated product-video workflows are unavailable
• STORE_LOGO_KEY: overrides the logo asset key without requiring a database store-settings update

The release stance is that missing optional providers should remove or block only the dependent feature, not the entire store.

Localization Model

Runtime locale handling is centralized in src/i18n/routing.ts and src/i18n/request.ts.

• Supported locales: en, ar, es
• Default locale: en
• RTL locale: ar
• Message loading: locale messages are merged over English fallback messages
• Store settings can enable a subset of the supported locales at runtime

Current content model strategy:

• Runtime locale routing already supports more than two locales
• Core business entities still use paired localized columns in many places, especially English and Arabic fields
• Spanish UI support is handled in the locale layer and message catalogs first
• Downstream teams that need more content-heavy localization should treat a scalable localized-content structure as the next evolution point for catalog and CMS entities

Localized Content Model

Today, the repo mixes two localization patterns intentionally:

1. messages/*.json for product UI and operational copy
2. Pair-based database fields such as titleEn / titleAr, descriptionEn / descriptionAr, storeNameEn / storeNameAr

That keeps the current schema stable while making locale expansion feasible. For OSS adopters:

• Keep English as the fallback language
• Add Spanish UI copy first if you extend the interface
• Consider a separate translation table or JSON content model if you need more than a few fully localized business languages

Demo Data And Seed Flow

This repo does not assume a single branded demo store. A practical starter flow is:

1. Push the schema with bun run db:dev:push
2. Create the marketplace-managed seller account with bun run db:create-internal-supplier
3. Create admin and seller users through your preferred local bootstrap path
4. Add categories, brands, sizes, colors, and store settings from the admin portal
5. Import catalog data only after MARKETPLACE_INTERNAL_SUPPLIER_ID is set when using migration scripts

The internal-seller scripts remain compatible with older naming in a few places, but the public configuration name is MARKETPLACE_INTERNAL_SUPPLIER_ID.

Compatibility Notes For Legacy Internal Names

The public OSS product is a neutral apparel marketplace starter. A few internal names remain for compatibility and should be treated that way:

• supplier: kept in schema, routes, and many internal APIs; public-facing copy should describe this role as seller where appropriate
• kid_photos: legacy table and account route name used by the optional reference-photo try-on flow; treat this as stored shopper reference imagery, not a required children-only feature
• shipped_to_kidsway: legacy order-status enum/storage value retained for compatibility; presentation layers should map it to neutral marketplace intake / handoff wording
• Kidsway size-estimator naming: legacy utility naming remains in the current AI sizing module; treat it as an internal compatibility artifact rather than public branding

If you extend the repo, prefer neutral naming in new public surfaces and add compatibility shims rather than risky sweeping renames in one release.

Customization Path

Common downstream customization points:

• Store identity: admin settings plus STORE_LOGO_KEY
• Locale availability: store_settings.enabled_locales and src/i18n/routing.ts
• Currency, region labels, and payment-badge display: store_settings and src/lib/store-config.ts
• AI assistant persona and tool behavior: src/lib/ai/system-prompt.ts and src/actions/ai/*
• Catalog attributes and merchandising metadata: attribute_definitions, product_attributes, and admin product flows
• Seller terminology and fulfillment wording: UI layer labels before schema-level enum changes
• Media pipeline: src/lib/storage/*, src/lib/runpod.ts, src/lib/runware.ts

Repository Naming And Packaging

• Package name: ai-apparel-marketplace-starter
• The package currently remains private in package.json to avoid accidental npm publishing while the repo is distributed as application source
• Public positioning for this release is an AI-powered apparel marketplace starter, not a fully generic marketplace framework

Verification Checklist For New Adopters

Before inviting real users or sellers:

1. Confirm the storefront loads with your store identity and currency.
2. Confirm admin login, seller login, and shopper signup behavior.
3. Upload and render product images from R2.
4. Place a test order through checkout.
5. Verify locale switching for English, Arabic, and any enabled subset you expose.
6. Enable optional AI/email providers one by one and test only the flows that depend on them.
7. Review docs/release-checklist.md before publishing a fork or production deployment.