Cadencea Web - Marketing & Account Management Website
The official marketing website and account management portal for Cadencea products. Built with Next.js 15, Supabase, and TypeScript.
IMPORTANT: This is NOT a web version of Cadencea Vault. Cadencea Vault is a desktop-only application (Electron-based). This website provides:
- Marketing and landing pages
- Desktop app download page
- User account management (profile, settings, billing)
- Future: E-commerce for VST software and sample packs
Project management is done exclusively in the Cadencea Vault desktop app.
Branches and previews
main is the live site: every push to it deploys to https://cadencea.app.cadencea-v2-beta is the v2 website in progress. Pushes create Vercel preview
deployments that are labelled "Preview" and kept out of search engines.
See docs/V2-PREVIEW.md for how to view and review the v2
site, which preview environment variables to set, and how to keep main and
v2 in sync.
🚀 Features
Authentication & Security
- Email/Password Authentication - Secure user registration and login
- Profile Management - Auto-created user profiles with editable information
- Secure Email/Password Changes - Safe account modification flows
- Route Protection - Middleware-based authentication for protected areas
- Row Level Security - Database-enforced data access control
- Audit Logging - Complete activity tracking for compliance
User Experience
- Order History - Real-time order tracking with RLS protection
- Newsletter System - Double opt-in subscription with compliance features
- Responsive Design - Mobile-first approach with modern aesthetics
- Error Handling - Comprehensive error states and user feedback
- Loading States - Smooth user interactions with proper feedback
Technical Excellence
- TypeScript - Full type safety throughout the application
- Next.js 15.5.25 - App Router with server-side functionality
- Supabase Integration - Modern BaaS with real-time capabilities
- Input Validation - Zod schemas for secure data processing
- Production Ready - Security, performance, and scalability focused
🛠 Tech Stack
- Frontend: Next.js 15.5.25, React 19, TypeScript
- Styling: Tailwind CSS v4 with custom design system
- Database: Supabase (PostgreSQL) with Row Level Security
- Authentication: Supabase Auth with custom flows
- Validation: Zod for input validation and type safety
- State Management: React Context with custom auth provider
📁 Project Structure
nextjs-boilerplate/
├── app/ # Next.js App Router
│ ├── api/ # API Routes (Server-side)
│ │ ├── auth/ # Authentication endpoints
│ │ │ ├── signup/ # User registration
│ │ │ ├── change-email/ # Secure email changes
│ │ │ └── change-password/ # Password updates
│ │ └── newsletter/ # Newsletter management
│ │ ├── subscribe/ # Double opt-in subscription
│ │ ├── confirm/ # Email confirmation
│ │ └── unsubscribe/ # Unsubscribe handling
│ ├── account/ # Protected user area
│ │ ├── settings/ # Profile management
│ │ └── subscription/ # Plan and invoices
│ ├── login/ # Authentication pages
│ ├── signup/ # User registration
│ └── layout.tsx # Root layout with auth provider
├── lib/ # Core utilities
│ ├── auth-context.tsx # React auth context
│ ├── supabase.ts # Database client
│ └── database.types.ts # TypeScript definitions
├── supabase/ # Database schema
│ └── migrations/ # SQL migrations with RLS
├── docs/ # Documentation
│ └── UPGRADE_PLAN.md # Comprehensive upgrade details
├── middleware.ts # Route protection
└── .env.example # Environment template
🚀 Quick Start
Prerequisites
- Node.js 18+ and npm
- Supabase account and project
- Basic understanding of Next.js and React
1. Environment Setup
# Clone the repository
git clone <your-repo-url>
cd nextjs-boilerplate
# Install dependencies
npm install
# Copy environment template
cp .env.example .env.local
2. Configure Supabase
- Create a new Supabase project at supabase.com
- Get your project URL and API keys from Project Settings > API
- Update
.env.local with your Supabase credentials:
NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key-here
SUPABASE_SERVICE_ROLE_KEY=your-service-role-key-here
3. Database Setup
The shared Supabase schema is owned exclusively by cadencea-api. Apply the canonical chain from cadencea-api/supabase/migrations through its protected deployment workflow. Do not run an independent Web migration set; see supabase/README.md.
After applying migration 029_cybersecurity_remediation.sql, configure the same NEWSLETTER_TOKEN_SECRET in the protected Web runtime and run npm run newsletter:backfill-unsubscribe-tokens once. This stores only hashes for existing confirmed subscriptions; never print or persist the derived URL tokens.
4. Start Development
npm run dev
Navigate to http://localhost:3000 and start using the application!
🔐 Security Features
Database Security
- Row Level Security (RLS) - Users can only access their own data
- Service Role Protection - Admin operations isolated to server-side
- Input Validation - All API inputs validated with Zod schemas
- SQL Injection Prevention - Parameterized queries via Supabase
Authentication Security
- Secure Password Handling - Supabase Auth with industry standards
- Session Management - Automatic token refresh and secure storage
- Route Protection - Middleware prevents unauthorized access
- CSRF Protection - Built-in Next.js security features
Compliance Features
- Audit Logging - All critical operations tracked
- GDPR Ready - User data deletion via Supabase
- Email Consent Tracking - Newsletter subscription compliance
- Data Minimization - Only collect necessary user information
📊 API Endpoints
Authentication
POST /api/auth/signup - User registration with profile creationPOST /api/auth/change-email - Secure email update with verificationPOST /api/auth/change-password - Password change with current password check
Newsletter
POST /api/newsletter/subscribe - Double opt-in email subscriptionGET /api/newsletter/confirm?token= - Email confirmation (HTML response)GET /api/newsletter/unsubscribe?token= - Render unsubscribe confirmation without changing statePOST /api/newsletter/unsubscribe - Consume a signed opaque unsubscribe token
🎯 Available Routes
Public Routes
/ - Homepage with feature overview/login - User authentication/signup - Account registration/products - Product showcase
Protected Routes (Require Authentication)
/account/settings - Profile management/account/subscription - Plan details and payment history/account/* - All account-related pages
🧪 Testing & Development
Manual Testing Checklist
Development Commands
npm run dev # Start development server
npm run build # Build for production
npm run start # Start production server
npm test # Run the regression suite
npm run security:secrets # Scan source for high-confidence credentials
🚀 Deployment
Vercel (Recommended)
- Connect your GitHub repository to Vercel
- Add environment variables in Vercel dashboard
- Deploy automatically on push to main branch
Environment Variables for Production
NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key
SUPABASE_SERVICE_ROLE_KEY=your-service-role-key
NODE_ENV=production
🔄 Future Enhancements (Database Ready)
Payment Integration
- Stripe webhook processing (database table ready)
- Order creation and fulfillment
- Download entitlements management
Advanced Features
- B2 signed download URLs
- Admin dashboard for user management
- Email marketing automation
- Advanced analytics and reporting
📚 Documentation
🆘 Troubleshooting
Common Issues
- Database Connection: Verify Supabase URL and keys in
.env.local
- RLS Errors: Ensure migrations ran successfully and RLS is enabled
- Authentication: Check middleware configuration and route protection
- CORS Issues: Verify Supabase project settings allow your domain
Support
For issues and questions:
- Check the Upgrade Plan documentation
- Review database migration files
- Verify environment variables are correctly set
- Test API endpoints with proper authentication
🏗 Architecture
This application follows modern best practices:
- Secure by Design - Security integrated from the ground up
- Type-Safe - End-to-end TypeScript for reliability
- Scalable - Database and API design supports growth
- Maintainable - Clear separation of concerns and documentation
- Production Ready - Error handling, logging, and monitoring
Built with ❤️ for the music production community.
