Cave Acoustics

A digital audio plugin store with license management, built with React Router v7 and deployed to Cloudflare Workers.

Tech Stack

• React Router v7 - Framework with SSR and data loading
• Better Auth - Authentication with social login (Google, Apple, Facebook)
• Drizzle ORM - TypeScript ORM
• Cloudflare D1 - SQLite database
• Cloudflare KV - Session storage
• Cloudflare R2 - Product file storage
• Stripe - Payment processing
• Resend - Transactional emails
• TailwindCSS v4 - Styling
• Shadcn UI - Component library

Features

• Product Catalog: Browse and purchase audio plugins
• License Management: Per-machine license activation with configurable limits
• Gift Cards: Purchase and redeem gift cards for account balance
• Account Balance: Apply balance to reduce checkout costs
• Upgrade Paths: Discounted upgrades between products
• Admin Dashboard: Manage products, licenses, users, and gift cards

Getting Started

Prerequisites

• Node.js 20+
• pnpm
• Cloudflare account (for D1, KV, R2)
• Stripe account
• Resend account (for emails)

Installation

pnpm install

Development Setup

1. Copy environment templates:

cp .dev.vars.example .dev.vars
cp wrangler.jsonc.example wrangler.jsonc

2. Configure .dev.vars with your API keys:

   • STRIPE_SECRET_KEY - Stripe secret key
   • STRIPE_WEBHOOK_SECRET - Stripe webhook signing secret
   • RESEND_API_KEY - Resend API key
   • Social auth credentials (Google, Apple, Facebook)

3. Set up the database:

pnpm db:apply
pnpm db:seed

4. Start the development server:

pnpm dev

The app runs at http://localhost:5173.

Default Users

After seeding:

• User: john@example.com / user@9900
• Admin: admin@example.com / admin@8899

Commands

Development

pnpm dev              # Start dev server with HMR
pnpm build            # Production build
pnpm typecheck        # TypeScript check (generates route types)
pnpm check            # Biome lint/format check
pnpm check:fix        # Auto-fix lint/format issues

Testing

pnpm test             # Run all tests
pnpm test:watch       # Run tests in watch mode

Database

pnpm db:generate      # Generate migrations after schema changes
pnpm db:apply         # Apply migrations to local D1
pnpm db:apply-prod    # Apply migrations to production D1
pnpm db:seed          # Seed local database
pnpm db:seed-prod     # Seed production database

Deployment

First-Time Setup

Create Cloudflare resources:

npx wrangler d1 create cave-acoustics
npx wrangler kv namespace create APP_KV
npx wrangler r2 bucket create cave-acoustics-files

Update wrangler.jsonc with the generated IDs.

Deploy

pnpm db:apply-prod    # Apply any pending migrations
pnpm deploy           # Build and deploy to Cloudflare Workers

Gradual Rollouts

pnpm deploy:version   # Deploy as a new version
pnpm deploy:promote   # Promote version to production

Project Structure

app/
├── components/       # React components
│   └── ui/          # Shadcn UI components
├── contexts/        # React contexts (cart)
├── hooks/           # Custom React hooks
├── lib/             # Server utilities
│   ├── auth/        # Better Auth configuration
│   ├── database/    # Drizzle schema and seed
│   └── validations/ # Zod schemas
├── middlewares/     # React Router middlewares
└── routes/          # Route modules
    ├── account/     # User account pages
    ├── admin/       # Admin dashboard
    ├── api/         # API endpoints
    ├── auth/        # Authentication pages
    ├── checkout/    # Checkout flow
    ├── gift-cards/  # Gift card purchase
    └── plugins/     # Product catalog

Documentation

See the docs folder for detailed documentation:

• Architecture Overview
• Commerce Flow
• Licensing System
• API Reference
• Admin Guide

License

Proprietary - All rights reserved.