AI SaaS Template Repository

This repository is prepared as a reusable Next.js template for AI SaaS products.

Before Publishing

• Rename the app and repository.
• Replace placeholder copy, pricing, legal pages, and external links.
• Confirm that the bundled Apache-2.0 license matches your intended distribution model.

Template Setup Guide

See TEMPLATE_SETUP.md for the placeholder map, branding checklist, and publish steps.

Local Development

1. Copy values from .env.example.
2. Install dependencies with pnpm install.
3. Initialize the local database with pnpm db:push.
4. Start the app with pnpm dev.

Direct Upload Configuration

This branch uses a direct-to-storage upload flow for images:

1. The browser calls a prepare endpoint with upload metadata and file signature bytes.
2. The server validates the request and returns a presigned PUT URL.
3. The browser uploads the file directly to R2 or S3.
4. The browser calls a complete endpoint, and the server verifies the stored object before returning the final URL.

Environment Variables

For Cloudflare R2:

• R2_ACCESS_KEY
• R2_SECRET_KEY
• R2_BUCKET_NAME
• R2_ENDPOINT
• R2_DOMAIN
• AUTH_SECRET

For AWS S3-compatible providers:

• S3_ACCESS_KEY
• S3_SECRET_KEY
• S3_BUCKET
• S3_ENDPOINT
• S3_REGION
• S3_DOMAIN
• AUTH_SECRET

Security Notes

• AUTH_SECRET must be set and should be at least 16 characters long. Upload tokens fail closed when the secret is missing or too short.
• Public anonymous reference images upload through /api/storage/upload-image/public.
• Authenticated/private uploads use /api/storage/upload-image.
• Private and public uploads use different object-key namespaces.
• Public reference-image uploads should be treated as temporary objects.

Required R2 / S3 Settings

• Configure bucket CORS for the browser origins that will upload directly.
• Allow at least:
  • Methods: PUT, GET, HEAD
  • Headers: Content-Type, Content-Disposition
• Configure lifecycle cleanup for the temporary public prefix:
  • uploads/public-temp/reference-images/

Validation Commands

• Policy and token tests:
  • node --import tsx --test tests/upload-policy.test.ts tests/upload-token.test.ts
• Typecheck:
  • rm -rf .next/dev && npx tsc --noEmit
• Lint:
  • pnpm lint --quiet
• Production build:
  • pnpm build

Template Checklist

• Update NEXT_PUBLIC_APP_NAME, domain, and support email.
• Replace demo assets in public/.
• Review locale content under src/config/locale/messages/.
• Replace sample legal content in content/pages/.
• Review admin setting placeholders in src/shared/services/settings.ts.
• Review GitHub Actions before enabling package or image publishing.