EnergyCurve

EnergyCurve is a Next.js App Router project for DJs. Create a playlist (manually or by pasting a tracklist), and the analysis engine resolves each track's energy, detects flow issues (drops, flat zones, early peaks, context violations), scores the set 1–10 with traceable penalty arithmetic, and suggests a stronger track order — all against the frozen v1 product rules.

What Was Set Up

• Next.js 16 App Router project with TypeScript strict mode and Tailwind CSS v4
• shadcn/ui configured with a minimal reusable UI base
• WorkOS AuthKit wired for login, sign up, callback handling, logout, and session-aware route protection
• App-controlled email/password auth plus optional Google sign-in via WorkOS social login
• Official AuthKitProvider mounted in the /dashboard and /backstage layouts (the routes proxy.ts matches) for App Router auth edge-case handling
• Supabase Postgres integrated as the application data layer only
• Server-only profile synchronization between WorkOS users and the profiles table
• Protected /dashboard route with server-side access validation
• Recoverable setup states for missing or invalid WorkOS configuration instead of raw framework crashes
• Initial SQL schema for profiles, playlists, and tracks
• Updated logo system with square, horizontal, monochrome, and icon SVG assets
• A first visual product pass for the landing page and dashboard, aligned to EnergyCurve's dark neon brand direction
• A locale-aware content base for global landing navigation copy
• Public marketing landing page rebuilt as a modular premium SaaS experience
• Product landing copy now structured across hero, features, how-it-works, differentiation, story, contact, CTA, and footer sections
• EN / ES language switching with persisted preference on the landing page
• Secure public contact form with route-handler validation, honeypot, basic rate limiting, and structured logging fallback
• Product strategy v1 documented in-repo, including ICP, MVP scope, KPIs, supported contexts, genre rules, and scoring assumptions
• Domain constants for EnergyCurve v1 now live in code for future product implementation
• Basic structured logging centralized for auth, dashboard fallback, and contact handling
• MVP auth documentation, auth hardening backlog, and initial auth workflow tests
• Documentation for setup, architecture, technical decisions, deployment, and validation

Stack

• Next.js 16.2.3
• React 19
• TypeScript
• Tailwind CSS v4
• shadcn/ui
• WorkOS AuthKit
• Supabase Postgres
• Vercel-ready deployment configuration
• Vitest for lightweight auth workflow tests

Roadmap Status

• Section 1 Product & Strategy: complete for v1 definition
• Section 2 Setup & Infra: complete for foundation
• Section 3 Auth & Users: complete for MVP
• Section 4 Playlist Input: complete for MVP (manual entry + paste-import)
• Section 5 Track & Analysis Engines: complete for MVP (v1 rules)
• Section 6 Recommendations & Results UI: complete for MVP (template-based)

See docs/roadmap-status.md for the detailed breakdown.

Project Structure

app/
  (en)/          English routes — marketing, auth, dashboard, backstage
  (es)/es/       Spanish marketing routes
components/
docs/
lib/
services/
supabase/migrations/
tests/
types/

(en) and (es) are route groups, so they do not appear in any URL: /pricing and /es/pricing are exactly where they look. They exist because each one has its own root layout, and a root layout is the only place <html lang> can be written — a single root cannot know which language the route below it renders in. Everything else about the shell is shared through components/layout/site-html.tsx.

Environment Variables

Copy .env.example to .env.local and fill in the values:

cp .env.example .env.local

Required variables:

• WORKOS_CLIENT_ID
• WORKOS_API_KEY
• WORKOS_COOKIE_PASSWORD
• NEXT_PUBLIC_WORKOS_REDIRECT_URI
• SUPABASE_URL
• SUPABASE_SERVICE_ROLE_KEY

Optional:

• NEXT_PUBLIC_POSTHOG_KEY — enables product analytics (PostHog); everything no-ops without it
• NEXT_PUBLIC_POSTHOG_HOST — defaults to https://us.i.posthog.com

Detailed explanations live in docs/setup-infra.md.

No additional environment variables are required for the public contact form in the current implementation.

Recommended Environment Split

• Local development: WorkOS Staging + http://localhost:3010
• Vercel production: WorkOS Production + https://energycurve.app
• Prefer a dedicated Supabase project for local/dev and another for production

Using separate WorkOS and Supabase environments keeps local tests from colliding with production identities or production data.

Local Development

1. Install dependencies:

npm install

2. Populate .env.local from .env.example.

3. Apply the database migrations (including supabase/migrations/0003_analyses.sql) from supabase/migrations/0001_initial_schema.sql and supabase/migrations/0002_align_v1_strategy.sql in Supabase SQL Editor or via the Supabase CLI.

4. Configure WorkOS:

   • Add http://localhost:3010/auth/callback as the redirect URI.
   • Add http://localhost:3010/ as the default logout URI.
   • Optional for Google login: enable Google Social Login in WorkOS Authentication.

5. Start the app:

npm run dev

Open http://localhost:3010.

Validation Commands

npm run test
npm run lint
npm run typecheck
npm run build

Manual Verification

Use the checklist in docs/setup-infra.md to verify:

• protected routing
• login and sign-up flows
• callback handling
• profile synchronization
• logout behavior
• optional Google sign-in
• branded landing and dashboard presentation
• EN / ES toggle and persisted language preference on the landing
• public contact form submission, validation, and error/success states
• strategy/domain alignment for EnergyCurve v1

Deployment Notes

• Set the same environment variables in Vercel for each environment.
• Configure the WorkOS redirect URI per deployed environment.
• Keep SUPABASE_SERVICE_ROLE_KEY server-side only.
• proxy.ts is used because Next.js 16 renamed middleware.ts to proxy.ts.
• Session persistence is handled by WorkOS AuthKit cookies plus proxy.ts for matched routes.
• For the cleanest setup, map Vercel Production to WorkOS Production and keep local .env.local on WorkOS Staging.
• Prefer a dedicated Supabase production project instead of sharing the same database with local/staging auth identities.

Known Limitations

• Analysis results are computed on request and not persisted yet; the "playlists analyzed" KPI and history views need a persistence layer.
• Recommendations are template-based (EN/ES); AI-generated narrative is a deliberate follow-up, not a v1 feature.
• Database access currently uses a server-only service role client; if future client-side data access is introduced, add RLS policies and a browser-safe client strategy.
• The auth test suite currently covers critical workflow logic, but browser-level end-to-end coverage is still future work.
• End-to-end auth verification still depends on real WorkOS and Supabase credentials being configured in the target environment.
• Until WorkOS Production is unlocked and wired, the Vercel deployment should be treated as pre-production rather than final production infrastructure.

Related Docs

• docs/setup-infra.md
• docs/product-strategy.md
• docs/roadmap-status.md
• docs/auth-users.md
• docs/auth-hardening-backlog.md
• docs/product-feature-01-manual-playlists.md
• docs/branding.md
• docs/brand-design.md
• docs/design-system.md
• docs/architecture.md
• docs/decisions.md
• AGENTS.md